ShadowScan handles audit credentials and security findings. Protect configuration, environment variables, record dumps, incremental state and reports as sensitive data. Redaction reduces accidental disclosure; it does not make reports public.
Reporting a vulnerability: open a private GitHub security advisory; Reporting says what to include and Supported versions which versions receive fixes. Never put credentials, tenant exports or exploit details in a public issue.
See the STRIDE threat model for boundary-specific threats, controls and residual risks, and the published hardening log for dated implementation evidence.
flowchart LR
U[Untrusted repositories, exports, API responses] --> B[Bounded parsers and confined readers]
C[Trusted operator configuration] --> E[Scanner engine]
B --> E
E --> R[Sanitization and coverage accounting]
R --> O[Sensitive reports and cache]
E --> H[Origin-bound HTTPS client]
H --> N[Remote provider APIs]
P[Explicitly allowlisted plugin] --> E
C --> P
The process boundary around a plugin controls its lifecycle, not its access to operator resources. A report remains sensitive after sanitization. Cloud SDKs have separate transports; use network-level egress controls where required.
The operator workstation or CI runner, scanner configuration and installed Python
packages are trusted. Third-party connector execution requires an exact-name
allowlist in options.plugins or repeatable --allow-plugin. Listing connectors
does not import plugin code. The allowlist is not a sandbox: an approved plugin
runs with scanner privileges. A spawned plugin worker is started without the
credential-shaped environment variables exported for the built-in connectors
(*_TOKEN, *_SECRET, *_KEY, *_PASSWORD, *_PAT, connection strings,
webhook URLs and URLs that carry a password, the CI, cloud SDK and package
tooling credential variables; the
plugin contract
lists them)
unless options.plugin_env names them, so they are neither in its
environment (os.environ, on Linux /proc/self/environ) nor in that of the
programs it starts; a thread-mode plugin shares the scanner's environment. This
keeps credentials from a plugin that does not look for them, not from one that
does. Process mode is lifecycle isolation, not a sandbox: the worker runs as the
scanner's user, so a plugin can still read its parent's environment, every
withheld variable and SHADOWSCAN_IDENTITY_KEY included, from
/proc/<ppid>/environ on Linux (other systems have equivalents), and every file
that user can read. Pass the built-in connectors' credentials through files
(such as the cloud SDKs' credential files) or a secrets manager rather than
exported variables, which keeps them out of the environment the scanner and
every program it starts carry; a plugin running as the scanner's user can
still read a file the scanner can. To keep a credential from an untrusted
plugin, run that plugin under a separate user or in a separate container, in a
scan job that does not hold the credential. Built-in connector names cannot be
replaced.
Remote responses, scanned repositories and offline exports are untrusted inputs.
Review signature packs before installation. Built-in signature IDs are reserved
unless options.allow_signature_override / --allow-signature-override explicitly
permits replacement. Directory walks do not follow signature/inventory symlinks.
Use dedicated read-only audit credentials and narrowly scoped inventory approvals.
CSV inventory approval identities preserve embedded line separators in quoted fields. Imported finding evidence is type-checked before postprocessing, and malformed cache entries are discarded in favor of a fresh scan. Provider error envelopes and malformed collection flags must not establish complete empty coverage, even when a response includes an empty collection field.
- Gateway inventory reconciliation requires authenticated caller-field assurance before an exact card binding grants registration or ownership. Operator-asserted and unverified names remain review candidates, without registration risk credit. Provider-field assurance still depends on the log producer's integrity and the supplied export's provenance; the scanner does not authenticate an offline export merely by parsing it.
- Make blueprint and Zapier pagination metadata are validated before collection can be considered complete. CODEOWNERS reads remain anchored to the source scan's directory descriptor. A root replacement detected before ownership lookup makes the scan incomplete; later replacements cannot redirect reads.
- Optional filesystem model/artifact inspection uses confined regular-file access, file identity checks and bounded metadata reads. It never executes packaged code, unpickles objects, loads tensor data or follows ONNX external data references. A recognized format is inventory evidence, not a working model or an agent. Lockfile parsing never runs a package manager.
- Optional Linux runtime inspection reads bounded maps and descriptor-link
metadata and, separately, allowlisted environment key names. It never opens
descriptor targets or
/proc/<pid>/mem, and environment values and mapped paths are not retained. PID namespace/start identity checks reject changed observations; denied or truncated selected inspection remains incomplete. These observations cannot establish arbitrary memory-only Python execution. - MCP/skill instruction review is static and bounded. It emits fixed heuristic explanations and locations, not a safety verdict, and never launches a discovered server, invokes a described tool or follows a supplied URL. Zeek JA4 ingestion and temporal DNS attribution likewise operate solely on supplied records; neither introduces live capture or DNS queries.
- Source and manifest inputs are decoded from UTF-8, from UTF-16 or UTF-32 with a byte-order mark, and for Python from the declared PEP 263 codec. An analyzed file with binary or undecodable content (dense NUL bytes, mostly invalid UTF-8; in other text, invalid bytes are replaced and noted while no 8 KiB window has more than four replaced characters and more than 10% of the window, and a few stray NUL bytes in large valid UTF-8 text are noted; names are matched without them, and a source file whose lexing differs with and without them is incomplete), or whose declared codec does not read ASCII as ASCII (UTF-16 or UTF-32 without a byte-order mark, UTF-7, EBCDIC), leaves coverage incomplete; ordinary binary assets are not text evidence. IAM wildcard and agent-definition front-matter matching shares the bounded matcher budget; keep an external worker/job deadline for hard isolation.
- Shared
HttpClientrequests require HTTPS without embedded credentials, and a URL containing a backslash is refused (it reads as one host to the URL parser and another to the transport). A credentialed endpoint taken from a remote response is also matched against an exact host, not a hostname suffix. Redirects and pagination stay on the configured origin. By default, private, loopback, link-local, metadata and other non-global addresses are rejected. The HTTPS adapter checks the addresses at connection time and connects directly to the checked address, retaining hostname TLS verification. A trusted private API requiresallow_private_origin: trueon its connector,options.allow_private_origin: true(every connector) or--allow-private-origin;--deny-private-originrefuses that grant for every connector, connector-level grants included. It does not revokeoptions.allow_instance_credentials: under that opt-in cloud connectors still contact the instance metadata service, and thecloud.gcpcredential transport accepts a private token endpoint. Pass--deny-instance-credentialsas well to keep cloud connectors off both. This exception does not relax origin or TLS checks. HTTP proxies, including environment proxy settings, are unsupported by this transport. - The shared HTTPS adapter bounds response acquisition, including status/header
delivery, separately from body reads. Cancellation interrupts the active socket
before it can be pooled for another request. System DNS resolution runs in a
bounded worker: the resolver call itself cannot be cancelled, but each wait
fails closed at its budget, at most 20 seconds, and a late result is
discarded before any connection. At connection the client timeout and the
acquisition deadline tighten the budget. The
validate_urlpreflight is tightened by the connector deadline and, forHttpClientrequests, by the client timeout and the client's deadline; its other callers (Git clone checks, SDK, MCP registry and JWKS preflights) and the clone pin lookup get only the connector deadline. A spent budget refuses without starting a lookup, and at most 32 lookups wait on the resolver at once; further ones fail closed once their budget passes without a free slot. A stalled resolver therefore holds a worker for a bounded time and cannot pile up threads. A process/job supervisor remains necessary for a hard execution limit, including external SDK transports. - Default shared HTTP responses and JSON/pagination helpers are limited to 16 MiB of decoded bytes, and each body must arrive within twice the client timeout (60 seconds by default). Oversized, slow and malformed collection responses fail collection, which marks the scan incomplete; a partial body is never analyzed. Explicit raw streaming callers are responsible for bounded reads and closure. Injected Requests sessions have their adapters replaced by destination policy. GitLab source-file downloads have a stricter 512 KB (512,000 bytes) per-file cap.
- Configured header values are validated before any request is built; a value
with control characters (typically a secret file's trailing newline) fails
without being echoed. The Okta
SSWSscheme is redacted likeBearerandBasic, and known configuration values are also redacted in theirrepr()-escaped spelling, which library errors use. - Connector warning/error log events contain fixed summaries, never diagnostic
payloads or exception arguments. Bounded, sanitized diagnostic details remain
in the scan report; treat reports as sensitive operational artifacts because
arbitrary upstream text can contain data beyond recognized secret formats.
An unexpected connector or repository failure raised inside third-party code
(an SDK or a plugin) is reported by exception type only.
Shared HTTP retry warnings and HTTP errors retain only a validated HTTPS
origin and status. Paths, userinfo, queries and fragments are omitted;
malformed URL diagnostics use fixed messages rather than parser exception text.
Opaque
api_token,foundry_token, andgithub_tokenvalues, including theGH_TOKENfallback, are sensitive. Diagnostic sanitization preserves credential context across errors, warnings and skip reasons; JSON publication also checks connector statistics together. - Live collectors assign record classification and collection scope after copying provider fields. Provider data cannot replace these local provenance fields. Offline exports remain untrusted operator-supplied records and do not authenticate the declared collection scope.
- Code/cloud credential evidence uses domain-separated HMAC pseudonyms under
one private key per Engine scan.
SHADOWSCAN_IDENTITY_KEYsupplies an optional stable key (at least 32 random bytes, hex/base64); it is never exported or cached. Direct library calls use an ephemeral process key. Without a stable key, credential-bearing results are rescanned rather than replaying cached pseudonyms. Key rotation invalidates cache reuse and collection comparability. Resource finding IDs remain stable. Old public credential digests and private legacy gateway binding mappings remain sensitive; see the credential evidence migration. options.connector_timeout_seconds/--connector-timeout-secondsdefaults to a 120-second cooperative completion deadline. Late connector results are discarded and coverage is incomplete. Legacyconnector_timeout/--connector-timeoutremain compatibility aliases; legacy YAML null uses the default. Python cannot forcibly interrupt blocked threads: calls may outliveEngine.run(). The CLI writes an incomplete report and exits without joining an abandoned worker once timeout handling returns. A filesystem replacement already in progress can finish after the timeout report; a cache or record file from a timed-out connector is unaccepted even if it exists. Record export manifests mark these entriesexported: false. Embedded callers still need a process supervisor; worker concurrency remains bounded. Enforce an external process or job deadline when a hard runtime limit is needed.- Azure App Service settings and OCI Function configuration are exported under
environment, so record dumps redact every value; Salesforce token values are never requested. - Cloud SDKs and Git use separate transports. A clone is pinned to the addresses
ShadowScan resolved and checked (
http.curloptResolve, proxy variables ignored), so Git does not resolve the clone host again; the cloud SDKs get no such pin. Network egress rules remain needed for those paths. Custom non-Requests transport doubles remain trusted extension/test mechanisms. - JWT classification remains unverified by default. Optional
jwks_urlsignature verification uses the shared transport with a bounded JWKS body and key count. Only allowlisted asymmetric algorithms and unambiguous eligible public keys are accepted. Symmetric and private keys are rejected.allowed_algorithmscan narrow the supported set;expected_issuervalidates an operator-supplied exact issuer. An unverified issuer does not select a JWKS source. Expiry and audience are not authorization checks: historical tokens are valid analysis inputs.metadata.verifiednever grants permission to act. - Offline exports use bounded reads without following symlinks, including
intermediate path components. YAML construction bounds nodes, aliases, depth,
merge expansion and expanded content before Python objects are constructed.
Sanitization bounds expanded structure and total replacement work. Ownership
patterns use bounded matching instead of backtracking regexes, and the code
scanner's IaC and agent front-matter patterns run on the bounded engine under
the per-input matching budget. Symbolic links count toward
max_filesand their checks stop at the connector deadline. A link is never followed: an in-tree link that stands for agent configuration has its target, resolved below the scan root, opened by its real path with the same confined opens and analyzed again under the link path. Limit hits and malformed inputs make coverage incomplete while retaining valid neighboring findings. These are resource safeguards, not process isolation or a universal deadline across every external SDK call. - Record dumps enforce replay's encoded-byte line and file limits and reject non-finite JSON numbers. Omitted valid export records remain available to live analysis, but the scan and export manifest are incomplete and the new dump is not published. Sanitizer safety-limit rejections skip the record and also abort dump publication. Preserve the manifest when replaying; a direct partial JSONL replay cannot establish collection completeness.
- Git history enrichment is disabled by default. Explicit
use_git: trueuses metadata-only commands with lazy fetching and every transport disabled; stdout and stderr share a 16 KiB limit, identity fields are capped, and cancellation or deadlines terminate the metadata process group. Unsupported Git behavior, malformed metadata or exceeded limits makes coverage incomplete. Metadata preflight rejects common-directory and alternate-object indirections, localinclude/includeIfconfiguration sections, internal links and special files. Localconfigandconfig.worktreeare read through confined descriptors within a 1 MiB limit; unsupported section syntax, encodings, continuations and multiline values fail closed. Inputs must remain immutable while Git runs; preflight is not a filesystem snapshot or process sandbox. Clone calls have a separate HTTPS-only policy: credentials stay scoped to the approved origin and redirects are disabled. Hooks and inherited Git overrides are suppressed, and clones verify the objects they receive. A termination signal or the job deadline stops in-flight clones and removes their checkouts. Unsafe branch values are dropped with incomplete diagnostics. Remote repository data cannot select an internal offline filesystem path. Keep Git patched and use disposable workers for untrusted inputs. - Reports and generated inventory stubs are written atomically with mode 0600,
never to a symbolic link and never through a directory link that another user
owns, a link inside another link's target included; the file is created and
renamed relative to the opened real directory.
..in the output path is resolved before any link is followed:-o mylink/../r.jsonwritesr.jsonbesidemylink, not in the parent of the link's target. An existing character device given as the output path (such as/dev/null) is written in place, and an existing named pipe only when the current user owns it with mode 0600; other non-regular paths are refused. Dump directories must be private (0700); record files use 0600 and unique per-instance filenames. An export manifest records provenance/completion without raw connector configuration. JWT records are never exported. No--dump-rawoption exists.
- By token shape: Source excerpts and the provider text connectors shorten for a report
(descriptions, instructions and prompts, welcome messages, trigger conditions, matching rules
and policy statements) are redacted before they are shortened; lists of names (scopes,
permissions, variable names) are cut first. Redaction withholds
recognized token formats (provider prefixes such as
sk-,ghp_,glpat-,glrt-,xoxb-,xapp-,AIza,ya29.,npm_,pypi-,dop_v1_,ABSKandbedrock-api-key-), JWTs, private key blocks (PEM, PGP, SSH2 and PuTTY, an unterminated one to the end of the text), URL userinfo (including schemes whose name contains an underscore, such as SQLAlchemy dialect URLs), credential query keys (includingauth,pwdandpat) and webhook or MCP-server path segments (Slack, Discord, Teams, Zapier hooks and Zapier MCP server URLs), theconfigquery field of a URL onsmithery.aior one of its subdomains (Smithery-hosted MCP servers take their own keys there as base64 or percent-encoded JSON), every cookie in aCookieheader, and compactname:valueheaders and passwords (x-api-key:value). A token or JWT is withheld behind a JSON-escaped line break or tab (\n,\t), a percent escape (%3D) or an underscore, and the prefixes no ordinary word contains (sk-proj-,ghp_,AKIA,eyJand similar) also behind a digit; a word that merely ends in a prefix's text (risk-,disk-) stays. URL userinfo is withheld whole when the password holds a raw/,?or#(postgres://u:example#pw@host). A URL inside another URL's text (redis://:pw@a,redis://:pw@b,?next=https://u:secret@b) is read as a URL as well. - By naming context: It also withholds values that their context names as credentials:
assignments, including annotated, multiline and R (
<-) expressions and every operator that joins a name to a value, with the operator kept (=>,:=,||=,+=,.=,?=); a quoted word or an opaque value compared with a sensitive name (if token == "...",!=,===,=~); names such aspassphrase,db_pass,smtp_pwd,SECRET_KEY_BASE,credsand npm's_auth; a list of API keys under a*_API_KEYSorapi_keysname, withheld whole (Open WebUI'sOPENAI_API_KEYS="k1;k2"); an upper-case*_PATname (AZURE_DEVOPS_EXT_PAT,ADO_PAT), while the lower-casedate_patnames a pattern and stays; and an ODBC connection string'sPwd=(a braced value whole,Pwd={a;b}); the value afterpassword,passwdandaccountin a netrc entry (machine h login u password v, on one line or one token per line, with keywords in any case as curl reads them,defaultanywhere on a line, vertical tabs and form feeds as blanks, also in a string with\n,\t,\vor\fescapes or PowerShell's`n, or written byecho), whatever it looks like, including a value that is itself a keyword (login account password vwithholds both words afteraccount), one after a Windows domain login (login CORP\fred, alsoCORP\\fredin a string, where an escape is read only on a line that holds a quote or an escape next to a keyword, or before one with blanks between), one after a token the format does not define once the entry'smachine,default,loginoruseris read, on the line of the entry's last token (machine h force yes password v,default force yes password v) or on a later line before apassword,passwdoraccountin the entry's region, which spans the eight lines from that of the entry's last token and ends before at a blank line or the next entry'smachine,defaultormacdef(machine h, thenforce yes, thenpassword von the next lines), one in an entry spread over adjacent string literals, which a closing quote, then blanks, line breaks, a+or a line continuation, then an opening quote join (("machine h\n", then"login u\n"and"password v\n")on the next lines), one after a keyword glued to a closing quote, which Python'snetrcreads as the next token (login "u"password v, also after a quoted word glued to the name, as inlogin "u""v"password v), an entry in a comment, also right after its#(a#after a blank or a line-break escape starts a comment, which runs to the end of its line or, in escaped text, to the next line-break escape: where escapes are read and its line holds an escape next to a keyword or before one with blanks between (machine h # c\n login u), a line-break escape before the#, or the same quote both before and after it, so the password of"machine h\n # bot\npassword v"is withheld, while a netrc file's own# Bob's share is C:\new\dataruns to the end of its line; a keyword that is a directory of a Windows path, right after a backslash or right before one that starts no escape, is no escape next to a keyword, so# home \\nas\user\fredand# C:\Users\bob\default\newrun to the end of theirs too), and the lines of a netrcmacdefmacro up to the empty line that ends it (a word afterdefault passwordin prose is withheld as well, and so is a word afterpasswordoraccountthat followsmachine,defaultorloginon its line or in its region, as inthe machine needs an account and a key,the default service account of the instance, ormachine learning toolswithcreate an account for each useron the next line); Yarn 1's.yarnrcregistry credentials writtenname value("//registry.yarnpkg.com/:_authToken" "v",_auth v); mappings, YAML block scalars, properties and INI entries;getenv-style calls; name/value records such as Kubernetesenvlists; XML elements andkey/valueattributes; DockerfileENV NAME value,setx,setenvand C#define; command-line options such as--api-key,--token,--password,--passphrase,--pat,--auth,curl -u user:secret,-H "X-Api-Key:value"(and any header whose name ends in a credential word, such asX-Token: valueorX-Functions-Key: value),-pafterdocker loginand other registry or cloud logins (az,az acr,oc,cf),sshpass -p, MySQL's-pVALUEand a literal echoed into--password-stdin; literal defaults of credentials read from the environment (process.env.OPENAI_API_KEY || "...",?? "...",or "...",?: "...",${OPENAI_API_KEY:-...}), also after a subscript or call read assigned to a credential name (azure_api_key: os.environ['K'] if PROD else '...',or '...', and an opaque one underazureKey: process.env['K'] ?? '...'); and string literals, including Python f-strings without replacement fields and backtick strings, passed to credential constructors and helpers such asAzureKeyCredential("..."), Rust'sAzureKeyCredential::new("..."), C#'s target-typedAzureKeyCredential credential = new("..."),HTTPBasicAuth("user", "..."),Credentials.basic("user", "..."),auth=("user", "...")andsetBearerToken("..."), including methods down a builder chain (builder().apiKey("...")). XML key/name attributes, element names and name/value records are read as settings: a hierarchical .NET name counts by its last:,__or.segment as well as whole (<add key="OpenAI:Secret" value="..."/>,- name: AzureOpenAI__Token,<entry key="openai.token">). A key/name attribute names the element's value attributes,<value>child and content, and the element's own name decides its content as well (<token key="openai.token" value="">...</token>). A literal that looks like an opaque key is also withheld from a name whose last word, ignoring trailing digits, names a credential: in assignments (openaiKey = "...",key = "...",KEY1=..., YAMLopenaiKey: ...), settings (<add key="AzureOpenAI:Key" value="..."/>,<OpenAIKey>...</OpenAIKey>,{name: OpenAIKey, value: ...}), options (--key ..., also in an argv list) anddotnet user-secrets set NAME VALUE; ordinary values under such names (<add key="CacheKey" value="users"/>,cacheKey: users-by-id) stay. It is also withheld from a lone unindented line after a sensitive key such astoken:. Variable references ($VAR,${{ secrets.X }}), environment variable names and placeholders stay visible, and so does a value that is exactly one read of an environment variable by an upper-case name (apiKey = process.env.OPENAI_API_KEY,api_key = os.getenv("OPENAI_API_KEY")). Only blanks and then the end of the line,;,,or a closing bracket may follow the read: with a default argument, a fallback literal, any other operand or a comment after it the value is withheld up to where the value lexer ends it (a quote, bracket,,or;of the expression). On a line that joins a credential name to a value (by:,=or a PHP or Ruby=>), or that gives a callee whose last word names a credential its arguments (sgMail.setApiKey(...), a builder's.apiKey(...)), every string literal after that name and the comment (//,#,/* */or an XML or HTML<!-- -->, read to its end when it runs past the line) keep their words, references and model names, but each token in them that looks like an opaque key is withheld, wherever the value ended: a fallback after a cut read (azureApiKey: process.env.K?.trim() || "...",os.environ[ 'K' ] if PROD else '...',cfg("a", "b") || "..."), a default argument (os.getenv("K", "...")) and a comment after the,or;that ends the value (apiKey: process.env.KEY, // old: ...,api_key = os.environ["KEY"]; # ...). A later line goes on with that value when it starts with a fallback operator (Black'sor "...",) or the line before ends with one, with comment lines between. Under each password's or secret's name on the line (password,passwd,pwd,passphrase,passorsecretas the last word, or a last word that runs words together and ends in one of them butpassandpwd, such asdbpasswordorCLIENTSECRET), not only under its first credential name ({ apiKey: ..., password: ... },client.setApiKey(k); ... { password: ... }), every string literal of the value up to the next entry of its own mapping, object or argument list is withheld whole, whatever its shape (dbPassword: process.env.DB_PASSWORD?.trim() || "...",db_password: os.getenv("K", "..."),clientSecret: process.env.S?.trim() || "...", a passphrase with spaces too), as the assignment form withholds it: after an environment read the matcher reports such a fallback whatever its shape. A keyword argument of the read is part of the value (cfg.get("db", "password", fallback="..."),env("P", default_value="..."),{ fallback: "..." }), and a closer that closes no opener on the line (an earlier pass withheld it with the start of the value, or a line before opened it) counts as one opened in the value, so the value goes on past the entries before it. Spans withheld for one value merge, so a literal whose start looks like a token is withheld to its end, not only that token. An upper-case variable name, a path, a URL, a placeholder and a literal of fewer than six characters stay. A template that assembles its text from expressions (${prefix}...) stays, as in assignments. A read is withheld as well when its variable name looks like a key pasted in place of the name: letters and digits alternate in a long run of it, or it has 16 characters or more and no_(an upper-case key or a base32 secret, with or without digits; a name such asHUGGINGFACEHUBAPITOKENis withheld with them). - Structured records: Structured name/value records that connectors
pass to the sanitizer read their name as a setting too, in either field
order (
{"name": "OpenAI:Secret", "value": "..."}, and an opaque value underOpenAIKey); an environment-style name there (PAGE_TOKEN) withholds only an opaque value. The fields of structured records (including every record of--dump-records) are withheld by name and by the words of the name: the last word, ignoring digits, issecret,token,password,passwd,pwd,passphrase,pass,credential(s),cookieorbearer(webhook_secret,bot_token,jwtSecret,db_pass), or iskeyafterapi,access,secret,private,signing,client,license,encryption,master,auth, a provider such asopenaior similar (client_key,openai_key). Cursors (next_token,page_token,skipToken), tokenizer tokens (eos_token), switches (requires_auth,has_secret), the barekeyof tags and S3 objects,sort_key,partition_keyandcache_keystay. A value that is not JSON-like (bytes, a set, an exception, a plugin's object) is converted to text before it is redacted, sodefault=strnever prints it raw. The rules added for settings, options, numbered names and YAML values run after the earlier rules, on their output, so they only withhold more. Credential constructor calls also accept whitespace and comments before the parenthesis, redundant parentheses, static C#$strings, verbatim multiline C# strings with doubled quotes, and multiline triple-quoted literals. Recognized unterminated quoted flow-record values and credential-call literals are withheld through their bounded text tail. Supported Go SDK imports bind credential-call receivers, including aliases and dot imports, before evidence truncation. This lexical recognition shares the sanitization work and binding limits; exhausting either withholds the evidence and marks coverage incomplete. Local shadowing can over-redact. Dynamic function reassignment is outside this bounded direct-call recognition. Known environment lookup fallback literals inherit the credential constructor's context even when their environment variable name is ordinary. Textual flow records support either name/value field order, braces and escaped quotes inside quoted values; preceding YAML sibling values are read within sixteen lines without crossing a list-item or mapping boundary. A quoted assignment value, a double-quoted option value and anauth=password close at their first quote that no backslash escapes, so{"log": "password: \"S\""}and--password "a\"S"withhold all ofS. Explicit signature and credential query fields are withheld in scheme-less URLs and copied query strings too. Command-specificllm -kand credential options glued after another option value are recognized; unrelated-kflags stay visible. Under key-like assignment names, an opaque identifier with at least three digit runs and only short letter fragments is also withheld; ordinary type names and--key usersvalues remain visible.aws configure setalso withholds positionalaws_access_key_id,aws_secret_access_key,aws_session_tokenand legacyaws_security_tokenvalues in shell text and literal argv lists, in any letter case and foraws,aws.exeandaws.cmd, includingdefault.andprofile.<name>.settings, global options (an unlisted--optionis read both as a flag and as taking a value), quoted words (including JSON-escaped quotes), POSIX, PowerShell backtick and cmd caret line continuations,#and//comments and string prefixes such asr"..."orb"..."between source argv elements, a bare--before the value, and an executable passed apart from its list (spawn("aws", [...]),spawn("aws", args=[...]),["aws"] + [...],Command::new("aws").args([...])). Native argv exports remove copies of those values from sibling fields too. Variable references, placeholders and metavariables stay visible. Adjacent quoted shell fragments, escaped bare values and source argv expressions beginning with a literal are withheld as a whole; the reader does not evaluate them. Entirely computed argv values remain outside this command reader. Recognition is bounded to 32 arguments and 16 KiB per candidate: a candidate that exceeds either limit fails sanitization closed rather than publishing a later value.
- Credentials in a file over
max_file_sizeare not read. The credential pass reads every analyzable file up tomax_file_size(1,000,000 bytes by default), and no further: a key in an oversize cassette, fixture or data export is not reported. The scan records the file as a coverage gap of a whole entry wherever it lies (it is never declared byprofile: cior weighed down as test code), so a few such files are tolerated within the coverage budget, listed instats[].coverage.detailsand counted insummary.tolerated_gaps, and more of them exit 3. An oversize dotenv file (.env,.env.production) always exits 3 while credentials are scanned; an oversize tool credential file (.npmrc,.netrc) is one such entry. Raisemax_file_size, or set--max-coverage-gap 0, where such a key must not be missed. - Limitations: Redaction cannot withhold a credential that nothing names or shapes as one,
so treat reports as confidential. A last-resort
pass also withholds, in evidence snippets and in finding descriptions,
titles and metadata, a quoted literal that looks generated: at least 20
token characters mixing upper case, lower case and digits, switching between
them often, with high per-character entropy. Hex digests, UUIDs and ordinary
identifiers keep their text; a short or low-entropy secret can still pass.
Outside report text, these forms can remain: an unprefixed
literal passed to an ordinary function, or nested in another call inside a
credential constructor (
AzureKeyCredential(str("..."))) when it does not look like an opaque key (one that does is withheld, as after any credential name on its line); a value assembled by a computed expression; after a read the value lexer cuts, inname: valueform or a callee's arguments, a literal under a name that is no password's or secret's that does not look like an opaque key, punctuated or not (apiKey: cfg("a", "b") || "correct-horse-battery-staple"), and under a password's or secret's name a literal of fewer than six characters or one that reads as an upper-case variable name (|| "HUNTERPASS"); a literal on a later line that the value lexer does not reach when that line does not start with a fallback operator and the line before does not end with one; a key in a block comment opened on a line that names no credential. Recognized credential calls with mixed interpolation withhold opaque static material; pure variable references remain visible. A few LLM SDK calls take a key positionally under a name that names no credential; the literal at the key's position in these is withheld: Semantic Kernel's .NET Azure OpenAI and OpenAI connectors (AddAzureOpenAIChatCompletion("deployment", endpoint, "..."),AddOpenAIChatCompletion("model", "..."), including the overloads that take an endpointUribefore the key, and their chat client, embedding, text-to-image and audio siblings and the matching services), go-openai'sopenai.DefaultConfig("..."),openai.NewClient("...")andopenai.DefaultAzureConfig("...", url),new OpenAiService("...")(com.theokanning.openai) andnew GoogleGenerativeAI("..."). Where a variable stands at the key's position, a later literal such as an organization ID may be withheld instead. Any other SDK call is an ordinary function, as is a key at a position no listed overload uses. The three go-openai helpers also recognize literal imports ofgithub.com/sashabaranov/go-openai, including aliases and dot imports; import references must be present in the full source passed to redaction. These forms can also remain: a word-like or short value under a name that is not itself sensitive and that lacks recognized opaque structure; a lowercase word after a space-separated option or as a fallback default; an option this list does not name, including command-specific one-letter options other than the recognized forms above; a positional argument of any other command besides the supported AWS credential settings; the part of an unquoted option value after a bracket, brace or comma; a literal fallback outside recognized credential contexts; URL userinfo that cannot be delimited: a password holding raw whitespace, quotes or angle brackets, one holding both a raw@and a raw/,?or#, a token without a colon that holds one of those (https://tok?en@host), a numeric password followed by one (https://user:00000000?x@host, which reads as a port), or a percent-encoded URL inside a query value (?u=https%3A%2F%2Fu%3Apw%40h); a token glued to a letter (apisk-proj-...) or, for a shorter prefix, a digit; a value named only by a comment (x = "..." # openai key); a bare value that is not an opaque key compared with a sensitive name (token == hunter2), a literal written before the operator ("..." == token) or compared with a subscript (headers["token"] == "..."); a readable value glued to the colon of a sensitive name (password:hunter2) or under a barepwd(the shell's working directory has that name); a field of a structured record whose name does not end in a credential word as above (OpenAIKey,key1, a bareauthorpass) and holds a value that looks like no credential; a record outside the bounded sibling/flow rules above; a value split across concatenated strings; a netrc entry spread over prefixed string literals or JavaScript template literals (Python'sb"machine h\n",f"..."orr"..."on the next lines, ``machine h\n- `` and so on), whose prefix or backtick the join of adjacent literals
does not read, so the entry ends after
machine; a netrc value after a token the format does not define on a later line than the entry's last token, which ends the entry there as prose after `machine learning` does, when a blank line, the next entry's `machine`, `default` or `macdef`, or the end of the eight-line region comes before the value's `password`, `passwd` or `account` (`force yes` and an empty line between `machine h` and `password v`), or in an entry whose `machine` is glued to other text; a commented-out netrc token that is not part of an entry in its comment, on a comment line of its own that holds no `machine` or `default` (`# password v` under a commented `# machine h`) or after an entry's own tokens (`login u # was password v`); the escaped lines after a netrc comment that those rules run to the end of its line, in escaped text where no escape sits next to a keyword or before one with blanks between, none breaks a line before the `#` and no quote comes both before and after it (`machine h # it's\nforce password v`); a netrc keyword written in quotes, which Python's `netrc` reads as the keyword, and the value after it (`login u "password" v`, `"machine" h login u password v`); and sensitive business data.
- `` and so on), whose prefix or backtick the join of adjacent literals
does not read, so the entry ends after
- Plural collection names are not sensitive names.
credentialsnames a credential, but the list or mapping under a pluralsecretsortokenskey keeps its values unless each one has a recognized shape or a sensitive name of its own:secrets: [prod-db-password]lists the names a secret store holds, which the AWS Secrets Manager, Google Secret Manager and OCI Vault collectors read and report as inventory, andtokens: 12is a count. A raw credential placed under one of those keys without a recognized shape therefore remains (the structural pass still removes it wherever a sensitive-named field holds the same value). Keep that in mind for a GitHub Actionssecrets:block or a Kubernetes manifest an operator pastes into an issue. In text, a name that ends in_API_KEYS(orapi_keysalone) is the exception: its value is a list of keys and is withheld, while plural*_TOKENSand*_SECRETSnames (MAX_TOKENS) keep theirs. That name rule and the upper-case*_PATone apply to text only: a structured record field or name/value record namedapi_keys,OPENAI_API_KEYSorADO_PATkeeps a value without a recognized shape, assecretsdoes. - Host-scoped query fields need the URL's host. A Smithery
configfield is withheld only in a URL that names its scheme and host (https://server.smithery.ai/...?config=...); a scheme-less copy or a bare query string keeps it, sinceconfigalone names no credential.
- Generated inventory resource bindings escape literal glob characters. Manual wildcard approvals remain possible and require operator review. Surface, provider and account restrictions still apply; ambiguous matches do not approve. Atlassian app keys require a concrete configured HTTPS site and an explicit account constraint on the approval. Unknown site identity leaves the scan incomplete and generated cards unbound; site fields in untrusted exports cannot supply or override that trusted scope.
- A SymBiote AgentBOM is operator-trusted inventory, read with the same bounded
UTF-8 reader and strict JSON and YAML loaders as other inventory. Each entity
collection it reads is bounded at 10,000 entries, and a malformed document is
an inventory validation error. Only literal subject identities become approval
bindings: external reference URLs, the A2A card URL and a complete
k8s:<cluster>/<namespace>/<kind>/<name>workload identity. Tool-server endpoints, package purls and workload UIDs are recorded as provenance only and approve nothing. The entry recordsverification: not-verified. Seals, Merkle trees and producer approvals are never verified or adopted; the Merkle root is only checked for agreement with the snapshot digest. - Configuration rejects missing or empty required environment substitutions,
duplicate YAML keys, unknown top-level/options fields and invalid gate levels.
Explicit
${VAR:-default}fallbacks remain an operator policy decision. - Incomplete scans exit 3 and set SARIF executionSuccessful=false. Only complete
results qualify for incremental reuse. Comparisons infer resolution only for
complete scans with matching collection, detection and finding-identity schemas,
and never for a finding in content the current scan declared (
--profile ci,declared_omissions) or tolerated (coverage budget,stats[].coverage) as unread. A gap the default profile discounts in test code (a warning ending "test code is discounted evidence") is counted in neither and does not hold a missing finding back. Explicit unmatched connector selections and unsupported/error exports fail visibly. Incremental input roots and ancestor symlinks are ineligible for reuse; pre/post hashing is not an atomic filesystem snapshot. Keep inputs immutable while scanning. Runtime telemetry attribution does not prove that a particular dependency executed.
See deployment and migration, scan semantics, and connector permissions.
Only the latest published release receives security fixes. Fixes land on
main and ship in the next release; there is no released-version backport
commitment. The project is an alpha (Development Status :: 3 - Alpha).
| Version | Supported | Notes |
|---|---|---|
| 0.1.4 | Yes | Latest published release (tag v0.1.4, PyPI, 2026-10-23). Report vulnerabilities against it. |
| 0.1.3 | No | Superseded by 0.1.4 on 2026-10-23; upgrade. |
| 0.1.2 | No | Superseded; upgrade. |
| 0.1.1 | No | Superseded; upgrade. |
main (unreleased) |
Fixes land here | Not a release. Pin a reviewed full commit SHA; a version number in the source is not evidence of publication. |
A version is published when it appears in the PyPI release history and as a release tag. Report the installed release version and artifact identity, or the full commit SHA for a source installation. Publication does not establish production acceptance for your environment.
Use a private GitHub security advisory. Do not include credentials, private exports or exploit details in public issues.
Report credential or private-data disclosure, redaction failures, unexpected access outside the scan root or configured network origin, allowlist bypasses, and malformed inputs that make incomplete coverage look complete. Reports about CI or release-evidence integrity also belong in the private channel.
Ordinary false positives, missed integrations and incorrect attribution can use the detection report form when the reproduction is safe to publish. A trusted component being compromised is outside the scanner's stated trust boundary; explain any demonstrated bypass rather than assuming the scanner protects a compromised host.
- The scanner release version and artifact identity, or full commit SHA for a source installation, plus the connector and collection mode. A candidate version alone does not identify a source revision.
- A minimal synthetic reproduction or public repository and commit, with expected and observed behavior.
- The security impact, affected artifacts and who could access them.
- Any relevant sanitized diagnostics; do not attach real credentials, JWTs or live tenant exports.
This volunteer project has one maintainer and cannot guarantee response times.
Use the advisory to coordinate reproduction, a fix and disclosure timing. Fixes
land on main; there is no released-version backport commitment. A confirmed
fix should include a regression test and any necessary rollout or migration
notes. Reporter credit and publication timing should be agreed in the advisory.
Only test repositories, accounts and tenants you are authorized to assess.