zaproxy/zaproxy · error · ApiException

illegal_parameter

illegal_parameter

Error message

illegal_parameter

What it means

ApiException(ILLEGAL_PARAMETER, filename) is thrown by CoreAPI.getChildPath when the resolved child path, after normalize(), does not start with the normalized parent path — i.e. the request attempts a path traversal ('..') outside the allowed directory. This is a deliberate security guard; ZAP logs 'Detected path traversal attack' before throwing. It protects endpoints that write/read session or other files under a fixed parent.

Source

Thrown at zap/src/main/java/org/zaproxy/zap/extension/api/CoreAPI.java:999

        throw new ApiException(Type.USER_NOT_FOUND, PARAM_USER_NAME);
    }

    /**
     * Returns a Path for the child file underneath the specified parent directory. Detects and
     * throws an exception if a path traversal attack is used.
     *
     * @param parent the parent directory
     * @param child the child path, which can include sub directories
     * @return a Path for the child file
     * @throws ApiException is a path traversal attack is used
     */
    protected static Path getChildPath(String parent, String child) throws ApiException {
        Path childPath = Paths.get(parent, child).normalize();
        Path parentPath = Paths.get(parent).normalize();
        if (!childPath.startsWith(parentPath)) {
            LOGGER.error("Detected path traversal attack {}", childPath);
            throw new ApiException(ApiException.Type.ILLEGAL_PARAMETER, PARAM_FILENAME);
        }
        return childPath;
    }

    private static Path getSessionPath(String path) throws ApiException {
        try {
            return SessionUtils.getSessionPath(path);
        } catch (IllegalArgumentException e) {
            throw new ApiException(ApiException.Type.ILLEGAL_PARAMETER, PARAM_SESSION, e);
        }
    }

    private static ApiImplementor getNetworkImplementor() throws ApiException {
        return API.getInstance().getImplementors().get("network");
    }

    private void setProxyChainExcludedDomainsEnabled(boolean enabled) {
        List<DomainMatcher> domains = getProxyExcludedDomains();

View on GitHub (pinned to 9d1970a436)

Solutions

1. Pass a plain filename without path separators or '..' so it resolves inside the intended parent.
2. Provide an absolute target path that is genuinely inside the parent directory the endpoint uses (e.g. ZAP session directory).
3. Resolve intended location first (e.g. File(parentDir, filename).getCanonicalPath()) and confirm it stays under the parent before calling.
4. Never interpolate untrusted input into the path parameter; validate/sanitize it client-side.

Example fix

// before
zap.core.save_session('../../tmp/evil.session', overwrite=True)  // illegal_parameter
// after
import os
name = os.path.basename(user_input)  # strips traversal
zap.core.save_session(name, overwrite=True)

import os
def safe_child(parent, child):
    base = os.path.realpath(parent)
    target = os.path.realpath(os.path.join(base, child))
    if not (target == base or target.startswith(base + os.sep)):
        raise ValueError(f'path escapes parent: {child}')
    return target

def is_within(parent, child):
    base = os.path.realpath(parent)
    t = os.path.realpath(os.path.join(base, child))
    return t.startswith(base + os.sep)

try:
    zap.core.save_session(filename, True)
except zapv2.exceptions.APIException as e:
    if 'illegal_parameter' in str(e):
        raise ValueError('path traversal rejected: use a bare filename inside the session dir') from e

When it happens

Trigger: Calling file-related core API actions (e.g. saveSession with a path, snapshot session) whose filename contains '../' or absolute paths that escape the parent directory supplied by the handler; any child parameter normalizing outside parentPath.

Common situations: Scripts passing user-supplied or temp paths directly into saveSession/loadSession; Windows vs Unix path mixing causing startsWith to fail unexpectedly; relative paths containing .. that the caller assumed would be resolved; automated fuzzers hitting ZAP triggering the guard.

Related errors

• ILLEGAL_PARAMETER
• ILLEGAL_PARAMETER
• ILLEGAL_PARAMETER
• Request to API URL {} with host header {} not permitted
• Request to API URL {} from {} not permitted

AI-assisted analysis of zaproxy/zaproxy@9d1970a436 (2026-09-05). Data as JSON: /api/errors/45818dc9dcf54b80. Report an issue: GitHub.