API Security Scanner Configuration

API Security Scanner Configuration

The API Security Scanner 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 <file>.

Configuration File Layout

# 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 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:

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.<id>.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:

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:

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:

xygeni apisecurity --dir . -c xygeni.apisecurity.yml -f json -o report.json --fail-on high