> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/api-security/api-security-scanner/api-security-scanner-configuration.md). # API Security Scanner Configuration ### API Security Scanner Configuration The [**API Security Scanner**](/xygeni-products/api-security/api-security-scanner.md) is configured through a YAML file, `xygeni.apisecurity.yml`, that controls framework autodiscovery, per-detector enablement and tuning, sensitivity classification overrides, and the flaw correlation rules. A default configuration is bundled with the scanner. Most projects do not need to override it. A project-specific configuration is loaded automatically when a file named `xygeni.apisecurity.yml` is present in the scan directory, or explicitly via `-c `. ### Configuration File Layout ```yaml # Framework autodiscovery — lightweight pre-pass that probes the project's # dependency manifests to load only the relevant detectors. autodiscovery: enabled: true confidence_threshold: 0.5 # minimum probe confidence to accept a framework # Frameworks allowlist / denylist. When `enabled` is non-empty, autodiscovery # is skipped. `disabled` always applies after autodiscovery. frameworks: enabled: [] # e.g. ['spring-mvc', 'openapi'] disabled: [] # e.g. ['flask'] # Per-detector configuration. Every detector in the catalog can be disabled # (`enabled: no`), have its severity overridden, or accept detector-specific # properties (see the per-detector pages). detectors: unauthenticated_endpoint: enabled: yes severity: high properties: # Glob patterns added on top of the built-in public-path allowlist. publicPaths: - "/v2/public/**" - "/api/marketing/**" excessive_data_exposure_java: enabled: yes properties: # Minimum confidence tier that fires. Default 'high'. Set to 'medium' # to include 'sensitive AND referenced in request' findings. minConfidence: high rate_limit_absence: enabled: yes severity: low broken_object_level_authorization: enabled: yes properties: idParameterPatterns: - id - "*Id" - "*_id" - uuid # Sensitivity classification overrides. Used to disable false-positive tags # on a per-project basis (e.g., a newsletter app where `email` is intentionally # public). sensitivityClassifier: ignore: # Field-level overrides — exact match on FQN (DTO + field name) - com.acme.user.NewsletterSubscriber#email # Path patterns - "**/PublicProfile.*" # Correlation rules — compose individual flaws into composite findings. correlation: enabled: yes rules: [] # see correlation.rules below ``` ### Framework Autodiscovery Before each scan, the autodiscovery probe walks the project directory looking for known manifest files (`pom.xml`, `build.gradle`, `package.json`, `requirements.txt`, `pyproject.toml`, `*.csproj`, `composer.json`, `go.mod`) and maps declared dependencies to framework detector IDs with a confidence score in `[0.0, 1.0]`. * When **probes find evidence** above `confidence_threshold` (default `0.5`), the scanner loads **only** the matching source-code detectors. Descriptor detectors (e.g., OpenAPI) always load since they are cheap and self-gate on filename. * When **probes find no evidence**, all detectors load as a safe fallback — an empty probe result means "inconclusive", not "nothing is present". * When **`frameworks.enabled` is non-empty**, autodiscovery is skipped entirely (user selection wins). Detected frameworks are logged at INFO level and recorded on the report's statistics under `detectedFrameworks` (id, confidence, source manifest), so it is always visible in the scan output why a particular detector was or was not loaded. ### Recognised Framework IDs The `frameworks.enabled` / `frameworks.disabled` lists use these IDs: | Language | Framework IDs | | -------- | ---------------------------------------------------- | | Java | `spring-mvc`, `jax-rs` | | C# | `aspnet-core` | | Python | `fastapi`, `flask`, `django`, `connexion` | | JS / TS | `express`, `nestjs`, `koa`, `fastify`, `hono` | | Go | `gin`, `echo`, `chi`, `fiber`, `gorilla`, `net-http` | | PHP | `laravel`, `symfony`, `slim` | | Any | `openapi` (covers OpenAPI 3.x + Swagger 2.x) | ### Per-Detector Configuration Every detector accepts the common keys: * `enabled: yes | no` — turn the detector off entirely. * `severity: critical | high | medium | low | info` — override the default severity. Useful when calibrating the noise floor during adoption. * `properties:` — detector-specific knobs. The most common ones are listed below; see the [detector catalog](/xygeni-products/api-security/api-security-detectors.md) for the complete reference. Notable detector-specific properties: | Detector | Property | Effect | | ------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `unauthenticated_endpoint` | `publicPaths` | Glob patterns added on top of the built-in allowlist (`/health`, `/metrics`, `/actuator/**`, `/.well-known/**`, …) for legitimately public endpoints. | | `excessive_data_exposure_*` | `minConfidence` | Lowest confidence tier that fires. Default `high`; `medium` widens to include "sensitive AND referenced in request" findings. | | `pii_leak_in_response_*` | `minConfidence` | Same shape as above. | | `broken_object_level_authorization` | `idParameterPatterns` | List of parameter-name patterns that indicate an object id (`id`, `*Id`, `*_id`, `uuid`, …). | | `broken_function_level_authorization` | `adminPathPatterns` | URL prefixes that look administrative (`/admin/**`, `/management/**`, `/internal/**`, `/system/**`). | | `cors_misconfiguration` | `dangerousOrigins` | Origin values treated as wildcard (`*`, `null`). | | `jwt_misconfiguration` | `dangerousAlgorithms` | Algorithms treated as unsafe (`none`, `HS256` with weak secrets). | | `mass_assignment` | `protectedAttributes` | Field names whose presence in the request body raises a finding (the privilege / identity / financial vocabularies). | | `rate_limit_absence` | `recognisedLibraries` | List of rate-limit library names checked for in handler files and entry points (extends the built-in defaults). | | `ssrf` | `urlParameterPatterns` | Parameter-name patterns suggesting a URL input. | ### Sensitivity Classification The sensitivity classifier tags parameters and DTO fields based on names, types, and framework-specific markers, producing one of these tags: `PII`, `PCI`, `PHI`, `CREDENTIAL`, `CRYPTO_MATERIAL`. The tags drive several detectors (`excessive_data_exposure`, `pii_leak_in_response`, `sensitive_param_unauthenticated`) and surface on the inventory regardless of whether flaws are produced. When the classifier mis-tags a field — for example, a newsletter-subscription app where `email` is the *intentional* product surface — the tag can be suppressed per-project: ```yaml sensitivityClassifier: ignore: - com.acme.user.NewsletterSubscriber#email - "**/PublicProfile.*" # all fields of any PublicProfile class ``` Suppressing the tag is the recommended way to silence the resulting finding, since it also removes the false sensitivity signal from the inventory itself. Disabling the *detector* (via `detectors..enabled: no`) is heavier and should be reserved for cases where the detector is genuinely not applicable to the project. ### Correlation Rules A correlation rule composes two or more individual flaws on the same endpoint into a single composite finding with its own severity, kind, and remediation. The built-in rule set includes: * **`pii_leak_in_unauthenticated_endpoint`** — emitted at **CRITICAL** when an endpoint carries both `pii_leak_in_response` and `unauthenticated_endpoint` findings. The composite replaces the two individual findings on the listing while preserving traceability back to its components. Custom correlation rules can be added per project. A rule has the shape: ```yaml correlation: enabled: yes rules: - id: my_composite_rule whenAll: # all listed findings must be present on the endpoint - pii_leak_in_response - unauthenticated_endpoint emit: detector: pii_leak_in_unauthenticated_endpoint severity: critical suppressComponents: yes # remove the component flaws from the report ``` ### Example — Full Project Configuration A worked example that pins frameworks, tightens the sensitive-data detectors, suppresses a known-public field, and gates the build at HIGH: ```yaml autodiscovery: enabled: no frameworks: enabled: - spring-mvc - openapi disabled: [] detectors: excessive_data_exposure_java: enabled: yes properties: minConfidence: high pii_leak_in_response_java: enabled: yes severity: high jwt_misconfiguration: enabled: yes mass_assignment: enabled: yes properties: protectedAttributes: - admin - role - isAdmin - balance - tenantId # project-specific privileged field rate_limit_absence: enabled: no # gateway-level limits are in place sensitivityClassifier: ignore: - com.acme.user.NewsletterSubscriber#email ``` Run with: ```bash xygeni apisecurity --dir . -c xygeni.apisecurity.yml -f json -o report.json --fail-on high ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xygeni.io/xygeni-products/api-security/api-security-scanner/api-security-scanner-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.