Skip to main content
Video tutorial · 1:38

API Risk Flags Reference

This is the reference for every risk flag the elchi-collector can raise on an endpoint. Flags are grouped by class; each entry lists its id, severity (Info 0 · Low 1 · Medium 4 · High 7 · Critical 10), OWASP API Security Top-10 (2023) mapping where one applies, a one-line meaning, and the primary remediation.

Which scoring axis a flag feeds — Threat or Exposure — is fixed per flag in the collector's severity catalog, not by class; see Risk Scoring. Exposure-axis flags are called out below. Info flags are descriptive context: they are shown, score 0 and never count as a finding.

Remediation kind: Envoy filter = add/tune an HTTP filter on the listener's HCM · TLS / transport = fix at the listener transport socket / codec · App-side = Envoy can't fix it, the app or IdP must · Informational = contextual signal, no action.

False-positive-first defaults

Every detector default is chosen for minimum false positives: the collector replays a corpus of benign production traffic shapes and attacks through its real pipeline on every test run, and benign traffic must raise no finding except genuine posture residuals. Stricter behaviour is always available through the collector configuration.

Active, historical and derived flags​

Per-event flags live in ClickHouse api_events_raw (TTL'd). Per endpoint, each fired flag is $addToSet-merged into api_inventory.risk_flags, so the stored set is the union of everything seen since the row was created — and each flag's latest sighting is stamped in flag_last_seen.<flag>.

The backend splits that lifetime set in two:

  • Active — last seen within the active window (policy.risk_active_days, default 7 days, 1–90; the per-row cutoff is max(now − risk_active_days, scores_reset_at)).
  • Historical — seen before the cutoff. A fixed flag ages from active to historical on its own; nothing has to be deleted.

The risk filter, the Risk dashboard, the PII and Auth Coverage dashboards, drift and the active scores all use active flags. PII categories and the auth markers follow the same rule (pii_last_seen.<category>, auth_last_seen, noauth_last_seen). A per-endpoint Reset or a project Rebaseline moves every earlier finding to historical at once.

Three flags are derived and decaying: the collector never stores them in risk_flags; it only stamps their evidence, and the backend evaluates them at read time within the active window. A derived flag whose evidence ever met the rule, but does not now, is reported as historical.

Derived flagRule (within the active window)
mixed_auth_schemes≥ 2 auth schemes other than none / cookie seen (auth_scheme_last_seen)
auth_inconsistentan authenticated request, an accepted anonymous request and an anonymous request refused on auth (401/403) — an optional-auth endpoint that never refuses anonymous callers is by design
cors_origin_reflection≥ detection.cors_reflection_min_origins (default 3, 1–8) distinct foreign reflected origins — registrable domain different from the API host's, by the Public Suffix List

Auth​

Authentication / authorization posture.

FlagSeverityOWASPMeaningRemediation
basic_auth_plaintextCriticalAPI2An Authorization: Basic header crossed the wire without effective TLS (no downstream TLS and no trusted TLS proxy) — a reversible username:password in clear text. Exposure axis.Terminate TLS on the listener (or declare the TLS-terminating LB in trusted_tls_proxy_cidrs); move off Basic auth. TLS / transport.
weak_token_ttlHighAPI2A JWT bearer token's lifetime (exp − iat) exceeds the configured threshold (default 30 days). Long-lived tokens are effectively static credentials. Exposure axis.Shorten access-token TTL at the IdP (minutes, not days); rely on refresh tokens. App-side.
unauthenticatedMediumAPI2An anonymous state-changing request (POST/PUT/PATCH/DELETE) was accepted (2xx/101/304, gRPC OK) on an API surface. Not raised for anonymous reads, pages/assets, auth flows, API docs, monitors, or requests authenticated outside an auth header (mTLS, a session-cookie name, a webhook signature header, a signed URL). Exposure axis.Informational if the endpoint is meant to be public. Otherwise add a JWT Authentication (or OAuth2 / Basic Auth) filter + an RBAC filter requiring an authenticated principal. Envoy filter.

Attack pattern​

Behavioural detectors and probe signatures firing on probable abuse. All feed the Threat axis.

FlagSeverityOWASPMeaningRemediation
brute_force_suspectCriticalAPI2Repeated 401/403 answers to credential submissions (mutating calls to an auth endpoint): ≥ 10 per consumer, or anonymously ≥ 20 per source IP when those are also ≥ 50% of that IP's attempts. Stateful (windowed).Local Rate Limit on the auth routes; Ext Authz for a cluster-wide limiter. Envoy filter.
payment_abuse_suspectCriticalAPI6Card testing: declined (4xx except 401/429) state-changing payment calls from one consumer — else one source IP — at or above the threshold and ≥ 50% of its payment calls. Stateful (windowed).Local Rate Limit scoped to payment routes + strong auth; Ext Authz for velocity/fraud scoring. Envoy filter.
threat_intel_hitCriticalAPI8Source IP matched a configured threat-intel feed. Enricher.RBAC deny policy for the offending CIDRs; front the listener with the WAF. Envoy filter.
bfla_suspectCriticalAPI5An anonymous request succeeded (2xx) on a privileged surface — admin, account management or data export — that is a write or targets an object. Payment is not treated as privileged (guest checkout, provider callbacks); API docs are excluded.RBAC binding privileged routes to permitted roles, driven from verified JWT claims. Envoy filter.
bola_suspectHighAPI1A consumer touched ≥ 50 distinct {id} values on one endpoint in 60 s with ≥ 10 of them answered 403/404 and forbidden ≥ 25% of the ids. API-key and mTLS consumers are skipped by default. Stateful (windowed).The real fix is an ownership check in the upstream. At the edge: Shield JWT claim_bindings, RBAC + JWT, Local Rate Limit to slow enumeration. App-side.
rate_anomalyHighAPI4One consumer exceeded the per-consumer request-rate threshold. Stateful (windowed); off by default.Per-consumer Local Rate Limit (429 + Retry-After). Envoy filter.
scanner_user_agentHighAPI8User-Agent matched a known scanner / pen-test tool (sqlmap, nuclei, nikto, …). Spoofable — corroborate. Enricher.RBAC deny on the scanner UA values, combined with rate limiting + WAF. Envoy filter.
vuln_probe_pathHighAPI8The path targets a well-known leak/exploit file (.env, .git, .aws, wp-login.php, server-status, …).RBAC deny the probe prefixes; confirm none of these files are served. Envoy filter.
path_scan_suspectHighAPI8Many distinct 404/405 paths from one consumer — else one source IP + User-Agent — inside the window: content discovery (gobuster, ffuf, dirb). Stateful (windowed).Local Rate Limit; RBAC deny sustained scanning CIDRs. Envoy filter.
impossible_travelHighAPI2The same consumer appeared on ≥ 2 continents with ≥ 2 continent switches in the window — or one switch onto a hosting / VPN autonomous system after a non-hosting session on another continent. Stateful (windowed); needs GeoIP.Treat the consumer as compromised: force re-auth, revoke tokens, add step-up MFA. App-side.
ip_rate_anomalyHighAPI4One source IP exceeded the per-IP request-rate threshold. Stateful (windowed); off by default.Per-source-IP Local Rate Limit; Network Local Rate Limit to cap connections. Envoy filter.
replay_suspectMediumAPI8The same signed or nonce-bound request (OAuth 1.0a / Hawk on any method; webhook HMAC signature, AWS SigV4 or HTTP Signature on a mutating method) was accepted (2xx) ≥ 3 times within 5 minutes on one listener. Keyed by a salted in-memory fingerprint; bearer / API-key / Basic / cookie / mTLS requests are never fingerprinted. Stateful (windowed).Reject repeated nonces / signatures upstream; enforce signature timestamps. App-side.
unsafe_method_on_readonlyMediumAPI8A state-changing method (POST/PUT/DELETE/PATCH) hit a path reserved for read-only probes (/healthz, /metrics, /favicon.ico, /robots.txt).RBAC permitting only GET/HEAD on probe paths. Envoy filter.

Transport​

Connection-layer and browser hygiene. Every transport flag is on the Exposure axis.

FlagSeverityOWASPMeaningRemediation
weak_tls_versionCriticalAPI8Envoy's own downstream TLS negotiated TLS 1.0 or 1.1. Toggle: weak_tls.Set the DownstreamTlsContext minimum protocol to TLSv1_2 (prefer TLSv1_3). TLS / transport.
plain_text_transportHighAPI8Served over plain HTTP to a public host — no TLS on the Envoy connection and no https from a trusted TLS-terminating proxy. Internal hosts are not flagged.Add a TLS transport socket; behind a TLS-terminating LB, list it in trusted_tls_proxy_cidrs. TLS / transport.
missing_hstsHighAPI8A 2xx HTML response over effective TLS (including a trusted TLS proxy) lacked Strict-Transport-Security. Not raised on 3xx / non-2xx or for monitors. Toggle: missing_hsts.Header Mutation appending Strict-Transport-Security on TLS listeners. Envoy filter.
cors_credentials_wildcardHighAPI8Access-Control-Allow-Origin: * together with Access-Control-Allow-Credentials: true.CORS filter with an explicit allow-origin list; never * with credentials. Envoy filter.
permissive_corsMediumAPI8Access-Control-Allow-Origin: null, or * on an internal host for a real cross-origin request. A * on a public API is correct CORS and is not flagged.CORS filter with an explicit allow-origin list. Envoy filter.
cors_origin_reflectionMediumAPI8Derived. The response echoed cross-site caller origins in Access-Control-Allow-Origin while allowing credentials, for at least cors_reflection_min_origins distinct foreign origins in the active window. An allow-list echoing the site's own front-ends is not reflection.Replace origin echoing with an explicit allow-list. Envoy filter.
cookie_missing_secureMedium—A Set-Cookie on an effective-TLS response lacked Secure. Cookie inspection only.Set Secure on cookies (app or Header Mutation). App-side.
cookie_samesite_none_insecureMedium—SameSite=None without Secure. Cookie inspection only.Add Secure or tighten SameSite. App-side.
cookie_missing_httponlyLow—A cookie without HttpOnly (CSRF/XSRF token cookies are exempt). Cookie inspection only.Set HttpOnly on session cookies. App-side.
missing_x_content_type_optionsLowAPI8HTML 2xx response lacks X-Content-Type-Options: nosniff.Header Mutation appending nosniff. Envoy filter.
missing_x_frame_optionsLowAPI8HTML 2xx response lacks X-Frame-Options (or a frame-ancestors CSP).Header Mutation appending X-Frame-Options: DENY. Envoy filter.
missing_cspLowAPI8HTML 2xx response lacks a Content-Security-Policy.Header Mutation appending a CSP. Envoy filter.
legacy_protocolInfo—Request used HTTP/1.0 or HTTP/1.1. Operational hygiene, not a finding.Optionally enable HTTP/2 on the HCM. Informational.
unverified_proxy_tlsInfo—Plain HTTP claiming x-forwarded-proto: https from a private / loopback direct peer that is not in trusted_tls_proxy_cidrs.If the peer is your TLS-terminating LB, add it to trusted_tls_proxy_cidrs. Informational.

Data leak​

Sensitive-data exposure.

FlagSeverityOWASPMeaningRemediation
pii_observedHighAPI3A reporting-enabled PII detector matched the path or a query value, or a leaked secret / JWT was collapsed to {secret} / {token}. Only the category is kept. Threat axis.Move PII out of URLs (POST bodies over TLS). App-side.
credential_in_queryHighAPI2A query parameter named like a credential carrier (api_key, access_token, password, client_secret, jsessionid, … — policy.credential_param_names) was sent in the URL. Only the name is inspected. Exposure axis.Move credentials to headers. App-side.
oversized_responseHighAPI4Response far larger than the endpoint's learned mean — a data-exfil canary. Never raised on data_export endpoints or file content types (csv/pdf/zip/tar/octet-stream/image/video). Stateful (per-endpoint mean).Enforce pagination / result caps upstream; verify object-level authorization. App-side.

Discovery​

Contextual surface signals. All on the Exposure axis.

FlagSeverityOWASPMeaningRemediation
version_disclosureLowAPI8A response header/banner leaked a software version (Server, X-Powered-By).Header Mutation removing version banners. Envoy filter.
sensitive_path_keywordInfo—Path contains a keyword of a commonly sensitive surface (admin, debug, actuator, metrics, pprof, …). Context for review, not a finding — vuln_probe_path carries the probe-only paths.Confirm the surface should be reachable. Informational.
internal_hostInfo—Host is loopback / RFC1918 / link-local / .local / .internal / .svc.cluster.local.Classification signal. Informational.
external_hostInfo—Host is public-shaped — internet-facing.Treat co-occurring findings on external hosts as higher priority. Informational.

Behavior​

Response-status and self-learned baseline signals.

FlagSeverityOWASPMeaningRemediation
error_rate_spikeMedium—The endpoint's client-error rate (4xx except 401/429) spiked above its self-learned baseline — the shape of fuzzing. 5xx outages do not count. Stateful (self-learning baseline). Threat axis.Classify the 4xx in Events; rate-limit the source. App-side.
error_statusLow—Upstream answered 5xx (not a shield block). An operations signal. Exposure axis.Investigate the upstream with the Errors dashboard. App-side.
client_error_statusInfo—Upstream answered 4xx (not a shield block).No action for isolated 4xx. Informational.
latency_anomalyInfo—Latency deviated from the endpoint's self-learned baseline.Investigate upstream performance. Informational.
geo_changeInfo—A consumer changed continent once in the window (one relocation / VPN toggle) without the hosting-AS escalation.Context for impossible_travel. Informational.

Consistency​

The same endpoint behaving differently across events. Both are derived (see above).

FlagSeverityOWASPMeaningRemediation
auth_inconsistentHighAPI5The endpoint served authenticated requests, accepted anonymous ones and refused anonymous ones within the active window — auth is enforced on some calls but not others. Threat axis.Enforce auth uniformly (JWT + RBAC); use Events to find the accepted anonymous calls. Envoy filter.
mixed_auth_schemesInfo—≥ 2 credential types (other than none / cookie) accepted on the same endpoint within the active window — usually deliberate (JWT for the web app, API key for partners).Context for an auth review. Informational.

OWASP API Security Top 10 (2023) coverage​

The collector sees metadata only (no request/response bodies, no outbound calls), which bounds what it can detect.

OWASP itemStatusFlags
API1 — Broken Object Level AuthorizationFullbola_suspect (plus per-consumer enumeration indicators)
API2 — Broken AuthenticationPartialbrute_force_suspect, weak_token_ttl, credential_in_query, basic_auth_plaintext, impossible_travel, unauthenticated
API3 — Broken Object Property Level AuthorizationOut of scopeRequires body inspection — ALS doesn't ship bodies. (pii_observed is the closest metadata signal.)
API4 — Unrestricted Resource ConsumptionPartialrate_anomaly, ip_rate_anomaly, oversized_response
API5 — Broken Function Level AuthorizationPartialbfla_suspect, auth_inconsistent (derived)
API6 — Unrestricted Access to Sensitive Business FlowsPartialpayment_abuse_suspect
API7 — Server-Side Request ForgeryOut of scopeOutbound-only — the collector doesn't see it.
API8 — Security MisconfigurationPartialweak_tls_version, missing_hsts, plain_text_transport, permissive_cors, cors_credentials_wildcard, cors_origin_reflection, vuln_probe_path, scanner_user_agent, path_scan_suspect, version_disclosure, missing_csp, missing_x_frame_options, missing_x_content_type_options, unsafe_method_on_readonly, threat_intel_hit, replay_suspect
API9 — Improper Inventory ManagementFoundationThe api_inventory catalog is the inventory — plus New APIs, Zombies, Drift and spec coverage.
API10 — Unsafe Consumption of APIsOut of scopeOutbound-only — not visible to the collector.
Out-of-scope is a data boundary, not a gap in effort

API3, API7, and API10 need request bodies or outbound-call visibility that a metadata-only access-log pipeline structurally cannot provide. For inline body inspection and property-level enforcement, that is Elchi Shield — which API Discovery feeds via suggest-policy.

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

API Discovery in Depth — Findings, Risks and CoverageYouTube ↗