Server Usage

dep-scan and cdxgen can operate in a server mode for distributed or centralized scanning. This mode exposes an HTTP API for on-demand analysis.

Starting the server

git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

The bundled docker-compose.yml now configures the dep-scan service with a development API key by default so the server can bind to 0.0.0.0. Override DEPSCAN_SERVER_API_KEY before starting the stack if you do not want to use the placeholder value.

Alternatively, start the server directly:

depscan --server --server-host 127.0.0.1 --server-port 7070

Local-only binds such as 127.0.0.1 continue to work without additional configuration.

To bind the dep-scan server to a non-local address, set an API key first.

export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070

All authenticated requests can then supply the key using either X-API-Key or Authorization: Bearer ....

[!IMPORTANT] As of 6.2.0, dep-scan refuses to bind to a non-local address without either DEPSCAN_SERVER_API_KEY or an explicit opt-in via DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.

If you need the old behavior for a short-lived trusted development setup, opt in explicitly:

export DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true
depscan --server --server-host 0.0.0.0 --server-port 7070

To scan git URLs, cdxgen server is mandatory. Use the argument --cdxgen-server to pass the url.

depscan --server --server-host 127.0.0.1 --server-port 7070 --cdxgen-server http://127.0.0.1:9090

The server listens for requests on the /scan endpoint. The type parameter is mandatory for all scan requests.

Example: Scanning a local SBOM file

curl \
  -H 'X-API-Key: dev-only-change-me' \
  --json '{"path": "/tmp/app/sbom.json", "type": "js"}' \
  http://127.0.0.1:7070/scan

Example: Scanning a remote Git repository

[!NOTE] cdxgen must be running in server mode for the below to work.

curl \
  -H 'Authorization: Bearer dev-only-change-me' \
  --json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' \
  http://127.0.0.1:7070/scan \
  -o app.vdr.json

Example: Uploading an SBOM file for analysis

curl -X POST \
  -H 'X-API-Key: dev-only-change-me' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/tmp/app/sbom.json' \
  http://127.0.0.1:7070/scan?type=js

[!WARNING] The dep-scan server is designed for trusted environments. It executes build tools and analysis logic based on the provided source code or SBOM. Deploying it in an untrusted network without additional security boundaries (e.g., network segmentation, containerization, WAF) is strongly discouraged.

Security Configuration

The server incorporates several built-in security mechanisms to mitigate common attack vectors. These are configurable via command-line arguments and environment variables.

Host and Path Allowlisting

Access to the /scan endpoint can be restricted based on the client's IP address and the filesystem paths accessed during the scan. This prevents unauthorized access and limits the scope of potential path traversal or local file inclusion attacks.

Configuration:

• --server-allowed-hosts: A space-separated list of IP addresses or hostnames permitted to access the server.
• --server-allowed-paths: A space-separated list of base directories that the server is allowed to read from or write to.

export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server \
  --server-host 0.0.0.0 \
  --server-port 7070 \
  --server-allowed-hosts 10.0.1.100 10.0.1.101 \
  --server-allowed-paths /scan_input /scan_output

When a scan request includes a path parameter, the server resolves it to its absolute path using realpath and verifies that it falls under one of the specified --allowed-paths. Requests for paths outside this allowlist are rejected with a 403 Forbidden response.

Client Request Path: /input/../secret.txt
Resolved Path:     /secret.txt
Allowed Paths:     [/scan_input, /scan_output]
Result:            Rejected (403)

URL Scheme Allowlisting

When scanning projects from a remote URL (e.g., a Git repository), the server validates the URL's scheme against a predefined set. This prevents the execution of potentially unsafe protocols.

By default, the allowed schemes are http, https, git, git+http, git+https. This can be customized using the DEPSCAN_SERVER_ALLOWED_GIT_SCHEMES environment variable.

export DEPSCAN_SERVER_ALLOWED_GIT_SCHEMES="https,git+https"

Requests containing URLs with schemes not in this list will be rejected with a 400 Bad Request response.

By default, dep-scan also rejects URLs that resolve to loopback, link-local, or private IP space. Only set DEPSCAN_SERVER_ALLOW_PRIVATE_URLS=true if your cdxgen-backed URL scanning workflow depends on private Git infrastructure and the deployment is already properly segmented.

Input Validation and Sanitization

• File Uploads: Uploaded BOM files are validated for JSON structure and CycloneDX format. The file extension must be .json, .cdx, or .bom.
• Content Length: The maximum size for incoming request bodies (including file uploads) is limited to prevent resource exhaustion. This limit is controlled internally and defaults to 100MB.
• Parameter Validation: The url parameter is parsed to ensure its scheme is allowed, its hostname resolves to an allowed address class, and incoming project types contain only supported characters.

Security Headers

The server automatically appends common security headers to all HTTP responses to mitigate client-side vulnerabilities:

• X-Content-Type-Options: nosniff
• X-Frame-Options: SAMEORIGIN
• X-XSS-Protection: 1; mode=block
• Strict-Transport-Security: max-age=31536000; includeSubDomains (if served over HTTPS)