Compare commits

..
Author SHA1 Message Date
yoni ba5cab24c2 docs(skill): plain wording for the unclear-chain case 2026-11-08 19:36:51 +00:00
yoni 0b78002686 fix(skill): walk every introducing chain before not_reached
For a transitive package the caller of the affected API is the package one
hop above it on each chain (body-parser for express > body-parser > qs),
not the direct dependency. Inspect that package on every chain; any chain
left unclear keeps the finding at imported.
2026-11-08 19:27:15 +00:00
yoni 7c490203ab feat(dependency): add the not_reached usage level
A dependency CVE can now be filed with reachability=not_reached: the
package is imported, but the usage analysis showed that the vulnerable
code of this advisory does not run in the codebase. It sits between
imported and not_imported on the evidence ladder and is decided per
advisory, with the check that showed it in reachability_evidence.

The dependency-cve-scanning skill explains when the level applies
(govulncheck finds no path, the parent of a transitive package never
references the affected API, the only call site is behind a condition
that is false here, build-only tooling) and keeps a partial or skipped
search at imported.
2026-11-06 12:20:53 +00:00
25 changed files with 304 additions and 557 deletions

No files matched your search

-2
View File
@@ -32,7 +32,6 @@ jobs:
wheel-platform: win_amd64
runs-on: ${{ matrix.os }}
timeout-minutes: 45
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
@@ -111,7 +110,6 @@ jobs:
if: startsWith(github.ref, 'refs/tags/')
needs: build
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
@@ -1,39 +1,48 @@
name: Binary
name: Package
on:
pull_request:
paths:
- pyproject.toml
- uv.lock
- strix.spec
- scripts/**
- strix/interface/tui/**
- .github/actions/**
- .github/workflows/binary.yml
push:
branches:
- main
paths:
- pyproject.toml
- uv.lock
- strix.spec
- scripts/**
- strix/interface/tui/**
- .github/actions/**
- .github/workflows/binary.yml
workflow_dispatch:
workflow_call:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
wheel:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
with:
go-version-file: strix/interface/tui/go.mod
cache-dependency-path: strix/interface/tui/go.sum
- uses: ./.github/actions/setup-python-env
- run: uv build --wheel
- name: Wheel ships the TUI sidecar and the viewer bundle
run: |
uv run --frozen python - <<'PY'
import glob, zipfile
(wheel,) = glob.glob("dist/*.whl")
names = zipfile.ZipFile(wheel).namelist()
assert "strix/bin/strix-tui" in names, names
assert "strix/interface/viewer/static/index.html" in names, names
assert not any(name.startswith("strix/interface/viewer/frontend/") for name in names)
assert not any(name.startswith("strix/interface/tui/cmd/") for name in names)
PY
- name: Install into a clean environment and run the CLI
env:
UV_EXCLUDE_NEWER: 5 days
run: |
uv venv --python 3.12 /tmp/strix-smoke
uv pip install --python /tmp/strix-smoke/bin/python dist/*.whl
/tmp/strix-smoke/bin/strix --version
/tmp/strix-smoke/bin/strix --help >/dev/null
- name: Vertex AI and Bedrock dependencies install with the wheel
run: /tmp/strix-smoke/bin/python -c "import google.auth.transport.requests, boto3"
binary:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
+61
View File
@@ -0,0 +1,61 @@
name: Python
on:
workflow_call:
permissions:
contents: read
jobs:
lock:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
- run: uv lock --check
ruff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
- run: uv run --frozen ruff check .
- run: uv run --frozen ruff format --check .
mypy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
- run: uv run --frozen mypy strix/
bandit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
- run: uv run --frozen bandit -r strix/ -c pyproject.toml
pytest:
name: pytest (${{ matrix.python-version }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ['3.12', '3.13', '3.14']
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
with:
python-version: ${{ matrix.python-version }}
- run: uv run --frozen pytest -q
+26
View File
@@ -0,0 +1,26 @@
name: TUI
on:
workflow_call:
permissions:
contents: read
jobs:
go:
runs-on: ubuntu-latest
defaults:
run:
working-directory: strix/interface/tui
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
with:
go-version-file: strix/interface/tui/go.mod
cache-dependency-path: strix/interface/tui/go.sum
- run: test -z "$(gofmt -l .)"
- run: go vet ./...
- run: CGO_ENABLED=0 go build -trimpath -o /dev/null ./cmd/strix-tui
- run: go test -race ./...
+27
View File
@@ -0,0 +1,27 @@
name: Viewer
on:
workflow_call:
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
defaults:
run:
working-directory: strix/interface/viewer/frontend
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '24'
cache: npm
cache-dependency-path: strix/interface/viewer/frontend/package-lock.json
- run: npm ci --no-audit --no-fund
- run: npm run build
- name: Committed viewer bundle matches the build
run: git -C "$GITHUB_WORKSPACE" diff --exit-code --stat -- strix/interface/viewer/static && test -z "$(git -C "$GITHUB_WORKSPACE" status --porcelain -- strix/interface/viewer/static)"
@@ -1,27 +1,14 @@
name: Workflows
on:
pull_request:
paths:
- .github/**
push:
branches:
- main
paths:
- .github/**
workflow_dispatch:
workflow_call:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
actionlint:
runs-on: ubuntu-latest
timeout-minutes: 10
env:
ACTIONLINT_VERSION: 1.7.12
ACTIONLINT_SCRIPT_REF: 914e7df21a07ef503a81201c76d2b11c789d3fca # v1.7.12
@@ -40,7 +27,6 @@ jobs:
zizmor:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
+26 -95
View File
@@ -15,107 +15,38 @@ concurrency:
cancel-in-progress: true
jobs:
lint:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
- run: uv lock --check
- run: uv run --frozen ruff check .
- run: uv run --frozen ruff format --check .
- run: uv run --frozen mypy strix/
- run: uv run --frozen bandit -r strix/ -c pyproject.toml
pytest:
name: pytest (${{ matrix.python-version }})
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python-version: ['3.12', '3.14']
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: ./.github/actions/setup-python-env
with:
python-version: ${{ matrix.python-version }}
- run: uv run --frozen pytest -q
python:
uses: ./.github/workflows/ci-python.yml
tui:
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
run:
working-directory: strix/interface/tui
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
with:
go-version-file: strix/interface/tui/go.mod
cache-dependency-path: strix/interface/tui/go.sum
- run: test -z "$(gofmt -l .)"
- run: go vet ./...
- run: CGO_ENABLED=0 go build -trimpath -o /dev/null ./cmd/strix-tui
- run: go test -race ./...
uses: ./.github/workflows/ci-tui.yml
viewer:
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
run:
working-directory: strix/interface/viewer/frontend
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '24'
cache: npm
cache-dependency-path: strix/interface/viewer/frontend/package-lock.json
- run: npm ci --no-audit --no-fund
- run: npm run build
- name: Committed viewer bundle matches the build
run: git -C "$GITHUB_WORKSPACE" diff --exit-code --stat -- strix/interface/viewer/static && test -z "$(git -C "$GITHUB_WORKSPACE" status --porcelain -- strix/interface/viewer/static)"
uses: ./.github/workflows/ci-viewer.yml
wheel:
package:
uses: ./.github/workflows/ci-package.yml
workflows:
uses: ./.github/workflows/ci-workflows.yml
ci-passed:
name: ci-passed
if: always()
needs:
- python
- tui
- viewer
- package
- workflows
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
persist-credentials: false
- uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
with:
go-version-file: strix/interface/tui/go.mod
cache-dependency-path: strix/interface/tui/go.sum
- uses: ./.github/actions/setup-python-env
- run: uv build --wheel
- name: Wheel ships the TUI sidecar and the viewer bundle
run: |
uv run --frozen python - <<'PY'
import glob, zipfile
(wheel,) = glob.glob("dist/*.whl")
names = zipfile.ZipFile(wheel).namelist()
assert "strix/bin/strix-tui" in names, names
assert "strix/interface/viewer/static/index.html" in names, names
assert not any(name.startswith("strix/interface/viewer/frontend/") for name in names)
assert not any(name.startswith("strix/interface/tui/cmd/") for name in names)
PY
- name: Install into a clean environment and run the CLI
- name: Every job succeeded
env:
UV_EXCLUDE_NEWER: 5 days
NEEDS: ${{ toJSON(needs) }}
run: |
uv venv --python 3.12 /tmp/strix-smoke
uv pip install --python /tmp/strix-smoke/bin/python dist/*.whl
/tmp/strix-smoke/bin/strix --version
/tmp/strix-smoke/bin/strix --help >/dev/null
- name: Vertex AI and Bedrock dependencies install with the wheel
run: /tmp/strix-smoke/bin/python -c "import google.auth.transport.requests, boto3"
failing=$(jq -r 'to_entries[] | select(.value.result != "success") | "\(.key): \(.value.result)"' <<< "$NEEDS")
if [ -n "$failing" ]; then
echo "$failing"
exit 1
fi
+20
View File
@@ -45,3 +45,23 @@ repos:
hooks:
- id: bandit
args: [-c, pyproject.toml]
# Additional Python code quality checks
- repo: https://github.com/asottile/pyupgrade
rev: v3.21.2
hooks:
- id: pyupgrade
args: [--py312-plus]
ci:
autofix_commit_msg: |
[pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
autofix_prs: true
autoupdate_branch: ""
autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
autoupdate_schedule: weekly
# pre-commit.ci cannot run `language: system` hooks; mypy runs via `make check-all`.
skip: [mypy]
submodules: false
+43 -7
View File
@@ -136,8 +136,12 @@ fi
- A finding with a call stack ⇒ `reachability=reachable_call_path`, put the
call-path excerpt (entrypoint → vulnerable function) in
`reachability_evidence`.
- Listed as affecting a required module but with no reachable symbol ⇒ fall
back to the import/symbol checks below (`imported` / `not_imported`).
- Listed as affecting a required module but with no reachable symbol ⇒ the
call graph found no path to the vulnerable function: `not_reached` when
application code imports the module (cite the govulncheck result and the
import), `not_imported` when nothing imports it. When govulncheck could not
analyze the module (build errors, missing deps), fall back to the
import/symbol checks below instead of claiming a level.
**All other ecosystems — import check, then symbol match:**
@@ -148,15 +152,25 @@ fi
`PyYAML` → `yaml`). No hits ⇒ `not_imported`, with the search scope stated
in `reachability_evidence`. For a **transitive** dependency, the check is
whether application code imports it directly; if not, it is reachable only
through the direct dependency — check whether the direct dep's usage can
hit it (if unclear, use `imported` when the direct dep is used at all).
through the packages that depend on it — walk every introducing chain
from the lockfile (e.g. `express > body-parser > qs`) and inspect the code
of the package one hop above the vulnerable one on each chain
(`body-parser`, not just `express`; its installed sources, or the class
references of its jar) for the affected API. No chain references it ⇒
`not_reached` (below), citing every artifact you inspected; referenced ⇒
that package's call is the usage site, continue the trace upward from
there. If you could not inspect every chain, or one of them is unclear,
the package is still loaded, so the level is `imported`, never
`not_reached`.
2. **Symbol match — per CVE, not per package.** Read each CVE's own advisory
(GHSA/NVD/OSV `affected[].ecosystem_specific.imports` or the advisory
text) for the affected functions/classes/APIs. Search application code for
those symbols (`ast-grep` pattern or `rg -n`). Hits ⇒
`vulnerable_symbol_used`, with repo-relative `file:line` of each hit (up
to a handful) in `reachability_evidence`. Imported but no affected-symbol
usage found (or the advisory names no symbols) ⇒ `imported`.
to a handful) in `reachability_evidence`. Imported, search completed, and
you can say why the vulnerable code does not run here ⇒ `not_reached`
(below). Imported but the search was partial, the result is unclear, or
the advisory names no symbols ⇒ `imported`.
Different CVEs on the same package usually affect **different** symbols
(one hits a parser, another a header check) — never copy one CVE's
verdict/evidence onto its siblings; run the symbol search against each
@@ -182,6 +196,23 @@ fi
dynamic loading, unparsable sources) ⇒ `unknown` and say why in
`assumptions`.
**`not_reached` — loaded, but this CVE's vulnerable code does not run here.**
Use it when the package is imported (so `not_imported` is wrong) and you
showed that the code path the advisory describes cannot execute in this
codebase, and `reachability_evidence` says what you checked. The judgement is
per CVE: it rests on what triggers *this* flaw (an affected function, a mode,
an option, a kind of input) against what this code does. Situations that
commonly support it, as inspiration rather than a checklist: the affected API
has no caller in application code and the search was complete; the only call
site is behind a condition that is false here (a polyfill for an older
runtime, a flag that is off, a path only a dev tool runs); a transitive
package's parent never references the affected API; the package is build or
test tooling that the shipped artifact never executes; a library compiled into
the runtime whose flaw sits in a mode the application never uses (a TLS server
path in a client-only service). An inconclusive or skipped check stays
`imported`. `not_reached` is still an evidence level, not proof of safety:
dynamic dispatch, reflection and framework wiring can evade static search.
Cheap-first budgeting: the import check is one search per package — always do
it. Do the per-CVE symbol match for every CVE whose advisory names affected
symbols (they can be batched into one multi-pattern search per package);
@@ -189,13 +220,18 @@ prioritize `critical`/`high`/KEV when the budget is tight; a CVE whose symbol
search was skipped may still be reported as `imported` (the import check is
real evidence), but its `reachability_evidence` must state that the
affected-symbol check was not performed, so a skipped search is never
mistaken for a completed one with no hits. Never let this analysis stall
mistaken for a completed one with no hits, and is never filed as
`not_reached`. Never let this analysis stall
reporting — `unknown` with a reason beats an unverified claim.
Anti-overclaim rules:
- `not_imported` still does NOT mean safe (dynamic `import()`/reflection/
framework wiring evade static search) — never phrase it as "not exploitable".
- `not_reached` needs the check that shows the vulnerable code does not run,
named in `reachability_evidence`; "no call found" after a partial search is
`imported`, and one CVE's `not_reached` never carries over to a sibling CVE
on the same package.
- `reachable_call_path` is reserved for call-graph tools (govulncheck); a
symbol grep hit is `vulnerable_symbol_used`, no matter how convinced you are.
- The tool rejects any level other than `unknown` without
-2
View File
@@ -64,8 +64,6 @@ Test every input vector with every applicable technique.
**Input Handling**
- Multiple injection types: SQL, NoSQL, LDAP, XPath, command, template
- For scalar search/filter/selector fields—including authorization fields—the delegated task must list each field and preload `query_language_injection`. One owner must run its matrix before `exact match` or `ruled out`
- Where different components validate and consume structured input, preload `idor`. Test raw parser differentials (duplicate members, type/number boundaries) and compare the checked identity with the acted-on identity
- Encoding bypasses: double encoding, unicode, null bytes
- Boundary conditions and type confusion
- Large payloads and buffer-related issues
-2
View File
@@ -50,8 +50,6 @@ Test each attack surface methodically. Spawn focused subagents for different are
- Injection testing on all input fields (SQL, XSS, command, template)
- File upload bypass attempts
- Search and filter parameter manipulation
- For every scalar search/filter/selector field, the delegated task must name it, preload `query_language_injection`, and require that skill's per-field matrix. Sibling-field probes or standalone metacharacters cannot justify `exact match`
- For structured authorization/object identifiers, preload `idor` and require raw duplicate-member permutations plus safe-number boundaries, comparing the checked identity with the read/changed/exported identity
- Redirect and URL parameter handling
**Authentication & Session**
+4 -4
View File
@@ -207,7 +207,7 @@ agent-browser snapshot -i
```
Credentials in shell history are a leak. For anything sensitive, use the
auth vault (see `references/authentication.md`):
auth vault (see [references/authentication.md](references/authentication.md)):
```bash
agent-browser auth save my-app --url https://app.example.com/login \
@@ -367,7 +367,7 @@ agent-browser click @e3
agent-browser record stop
```
See `references/video-recording.md` for
See [references/video-recording.md](references/video-recording.md) for
codec options, GIF export, and more.
### Iframes
@@ -491,8 +491,8 @@ snapshot — fall back to `eval` in the iframe's origin or use the
**Authentication expires mid-workflow**
Use `--session-name <name>` or `state save`/`state load` so your session
survives browser restarts. See `references/session-management.md`
and `references/authentication.md`.
survives browser restarts. See [references/session-management.md](references/session-management.md)
and [references/authentication.md](references/authentication.md).
## Global flags worth knowing
+2 -4
View File
@@ -53,13 +53,11 @@ Object-level authorization failures (BOLA/IDOR) lead to cross-account data expos
**Enumeration Techniques**
- Alternate types: `{"id":123}` vs `{"id":"123"}`, arrays vs scalars, objects vs scalars
- Edge and numeric boundaries: null, empty, 0, -1, MAX_INT, and exact and adjacent values around each runtime's safe-integer and overflow limits, including decimal and exponent forms
- Duplicate keys/parameter pollution: send raw query strings such as `id=1&id=2` and raw JSON such as `{"id":1,"id":2}` so serializers cannot collapse duplicates. Use conflicting values in both orders to determine parser precedence
- Edge values: null/empty/0/-1/MAX_INT, scientific notation, overflows
- Duplicate keys/parameter pollution: `id=1&id=2`, JSON duplicate keys `{"id":1,"id":2}` (parser precedence)
- Case/aliasing: userId vs userid vs USER_ID; alt names like resourceId, targetId, account
- Path traversal-like in virtual file systems: `/files/user_123/../../user_456/report.csv`
For gateways, workers, and multi-service APIs, treat authorization as an identity invariant: the object authorized must equal the object read, changed, or exported. Run the representation and duplicate-member matrix even after one variant succeeds. Compare response identity/content, not status alone.
**UUID/Opaque ID Sources**
- Logs, exports, JS bundles, analytics endpoints, emails, public activity
- Time-based IDs (UUIDv1, ULID) may be guessable within a window
@@ -14,7 +14,6 @@ NoSQL injection exploits the mismatch between how applications pass user input t
- Form fields with bracket notation (`field[$ne]=`) coerced into operator objects by Express, PHP, and similar middleware
- URL-encoded JSON in query strings, headers, and cookies
- GraphQL variables passed directly into resolver-level NoSQL filters
- Scalar strings compiled into expression languages are a separate construction class. Load `query_language_injection`
**Code patterns that enable injection**
- Raw filter dicts/objects from user input handed to `find`/`findOne`/`aggregate`
@@ -242,7 +241,7 @@ DoS surface (use only with explicit authorization scope):
1. **Identify query-receiving endpoints** — login, search, filter, lookup
2. **Determine input format** — JSON body vs form fields vs URL params
3. **Send error-probing payloads** — test malformed operator objects and watch for MongoDB/driver errors. For scalar expression construction, load `query_language_injection`
3. **Send error-probing payloads** — malformed operator objects; watch for MongoDB/driver errors
4. **Attempt operator injection** — `$ne`, `$gt`, `$regex` against login endpoint
5. **Confirm boolean oracle** — response, status, redirect differs between true/false predicates
6. **Extract data blindly** — character-by-character `$regex` on sensitive fields (token, reset code)
@@ -1,20 +0,0 @@
---
name: query-language-injection
description: Scalar injection into embedded query languages, especially apparent exact-match authorization filters compiled as JSONPath, JMESPath, OData, Lucene, LDAP, Cypher, or XPath
---
# Query-Language Injection
An HTTP string can become syntax when a downstream component builds a query or policy expression. Treat every accepted search, filter, selector, and authorization scalar as an independent sink.
## Mandatory Matrix
For each named scalar field:
1. Establish known-match and known-no-match controls while all sibling fields stay fixed.
2. With known match `V`, execute these four JSONPath-style closure cells on the field itself: `V' || @.<field> == @.<field> || 'V`, `V' && @.<field> != @.<field> && 'V`, `V" || @.<field> == @.<field> || "V`, and `V" && @.<field> != @.<field> && "V`. Balance the expected suffix and adapt field and operator syntax for other grammars. Constant-only expressions may be rejected.
3. Do not substitute standalone metacharacters, generic SQL probes, object payloads, or tests of a sibling field for any cell.
4. Repeat across plausible grammars inferred from behavior or errors. An empty result may represent a swallowed parser exception.
5. Confirm impact through broadened, cross-tenant, privileged, or otherwise forbidden results—not a parser error alone.
Do not conclude `exact match`, `safe`, or `ruled out` until this matrix ran on every scalar sink, or a specific non-concatenating control was identified.
@@ -1,6 +1,6 @@
---
name: semantic-confusion
description: Cross-component semantic confusion testing for parser differentials, normalization mismatches, email and IDNA identity drift, overloaded fields, lifecycle state drift, internal redirects, protocol translation, and validator-to-sink inconsistencies
description: Cross-component semantic confusion testing for parser differentials, normalization mismatches, overloaded fields, lifecycle state drift, internal redirects, protocol translation, and validator-to-sink inconsistencies
---
# Semantic Confusion
@@ -59,27 +59,6 @@ The highest-signal condition is `security_check(value_A)` followed by `sink(tran
- Test malformed Unicode and replacement behavior; a rejected code point may become an allowed delimiter or wildcard later.
- Test path, query, and fragment separately. Browsers and routers commonly transform each source differently.
### Email and Account Identity Drift
Treat an email address as both a principal selector and a delivery destination. Trace the complete boundary before testing:
```text
submitted or identity-provider address
-> application normalization / IDNA
-> database comparison and collation
-> selected local principal
-> token, session, invitation, or link binding
-> recipient or linked identity consumed by the final service
```
- Cover recovery, magic links, invitations, registration uniqueness, email changes, and OAuth/OIDC account linking. Test case/accent-insensitive collations, Unicode normalization, IDNA U-label/A-label conversion, trailing dots, and provider canonicalization only when the observed stack supports them.
- In black-box testing, report the observed equivalence and routing behavior. Do not name a specific collation, normalizer, or provider algorithm without source, configuration, or version evidence.
- Determine whether two non-identical addresses can select the same protected principal while SMTP or an identity provider routes them to different owners. The address that receives authority must identify the same principal selected by the security check.
- In recovery flows, compare the submitted address with the selected account's stored canonical address. A fuzzy lookup followed by delivery to the submitted value is high risk; an exact lookup plus delivery to the stored value is the primary negative control.
- Use only an explicitly authorized attacker-controlled mailbox or test domain. Derive a bounded variant set from the deployed collation and canonicalizers rather than spraying external domains or the Unicode range.
For a recovery, magic-link, or invitation finding, a generic success response is not proof. Demonstrate that the variant selects the protected principal, the issued authority reaches the controlled mailbox or identity, and redemption yields the protected principal's access. If delivery or redemption cannot be observed, keep the path `needs_follow_up`.
### Field and Type Overloading
- Identify shared fields reused for different concepts: path vs URL, content type vs handler, display name vs executable name, route vs filesystem location.
@@ -191,8 +170,6 @@ A valid confusion finding should include:
- Different error messages with identical final authorization and sink behavior
- A parser accepts odd syntax but downstream consumers preserve the same safe meaning
- A normalization difference visible only in logs, with no security decision between representations
- A Unicode or Punycode lookalike that neither selects another principal nor receives authority intended for that principal
- A permissive database comparison where recovery delivery still uses the selected account's stored canonical address
- WAF bypass where the application itself rejects the request identically
- Version-specific behavior claimed as universal without testing the relevant deployment
- A search-path candidate that is attacker-named but cannot be created, claimed, loaded, or executed
-56
View File
@@ -1,56 +0,0 @@
"""In-memory bearer refresh for HTTP MCP connections."""
from __future__ import annotations
import asyncio
import logging
from typing import TYPE_CHECKING
import httpx
if TYPE_CHECKING:
from collections.abc import AsyncGenerator, Awaitable, Callable
logger = logging.getLogger(__name__)
class RefreshingBearerAuth(httpx.Auth):
def __init__(
self, token: str | None, refresh_token: Callable[[], Awaitable[str | None]]
) -> None:
self._token = token
self._refresh_token = refresh_token
self._lock = asyncio.Lock()
self._refresh_generation = 0
def _authorize(self, request: httpx.Request, token: str | None) -> None:
if token:
request.headers["Authorization"] = f"Bearer {token}"
else:
request.headers.pop("Authorization", None)
async def async_auth_flow(
self, request: httpx.Request
) -> AsyncGenerator[httpx.Request, httpx.Response]:
sent_token = self._token
sent_generation = self._refresh_generation
self._authorize(request, sent_token)
response = yield request
if response.status_code != 401:
return
async with self._lock:
if self._token == sent_token and self._refresh_generation == sent_generation:
try:
token = await self._refresh_token()
except Exception as exc: # noqa: BLE001
logger.warning("MCP bearer refresh failed (%s)", type(exc).__name__)
token = None
self._refresh_generation += 1
if token and token != sent_token:
self._token = token
retry_token = self._token
if retry_token and retry_token != sent_token:
self._authorize(request, retry_token)
yield request
+6 -23
View File
@@ -39,11 +39,10 @@ from strix.tools.mcp.session import McpConnectionUnavailableError, SupervisedMcp
if TYPE_CHECKING:
from collections.abc import Awaitable, Callable, Mapping
from collections.abc import Callable
import httpx
from strix.tools.mcp.auth import RefreshingBearerAuth
from strix.tools.mcp.config import McpConnectionConfig
from strix.tools.mcp.registry import McpConnectionRequest, McpRegistry
@@ -122,9 +121,7 @@ class _QuietMCPServerStdio(MCPServerStdio):
return _quiet_stdio_streams(self.params)
def _build_server(
config: McpConnectionConfig, bearer_auth: RefreshingBearerAuth | None = None
) -> BuiltMcpServer:
def _build_server(config: McpConnectionConfig) -> BuiltMcpServer:
"""Construct (but do not connect) the SDK server for one connection.
The returned tuple carries the server and, for HTTP connections, a recorder
@@ -164,13 +161,13 @@ def _build_server(
timeout: httpx.Timeout | None = None,
auth: httpx.Auth | None = None,
) -> httpx.AsyncClient:
client = create_mcp_http_client(headers=headers, timeout=timeout, auth=bearer_auth or auth)
client = create_mcp_http_client(headers=headers, timeout=timeout, auth=auth)
client.event_hooks.setdefault("response", []).append(recorder)
return client
http_params: MCPServerStreamableHttpParams = {
"url": cast("str", config.url),
"headers": {} if bearer_auth is not None else _auth_headers(config),
"headers": _auth_headers(config),
"timeout": config.http_timeout_seconds,
"sse_read_timeout": config.sse_read_timeout_seconds,
"httpx_client_factory": httpx_client_factory,
@@ -303,12 +300,9 @@ async def connect_mcp_servers(
configs: list[McpConnectionConfig],
*,
max_concurrency: int = 6,
token_refreshers: Mapping[str, Callable[[], Awaitable[str | None]]] | None = None,
) -> list[ConnectedMcpServer]:
"""Connect MCP configs concurrently under a fixed bound.
``token_refreshers`` optionally supplies a bearer refresher by connection name.
Each connection becomes a :class:`~strix.tools.mcp.session.SupervisedMcpSession`
that owns ``connect()``, the held-open session, and ``cleanup()`` on one
dedicated task, so a later background failure in one session is contained to
@@ -331,10 +325,7 @@ async def connect_mcp_servers(
async def connect_one(config: McpConnectionConfig) -> ConnectedMcpServer | None:
async with semaphore:
session = SupervisedMcpSession(
config,
refresh_token=token_refreshers.get(config.name) if token_refreshers else None,
)
session = SupervisedMcpSession(config)
sessions.append(session)
try:
if not await session.start():
@@ -390,14 +381,7 @@ async def attach_mcp_requests(
ends).
"""
request_by_name = {request.config.name: request for request in requests}
connections = await connect_mcp_servers(
[request.config for request in requests],
token_refreshers={
request.config.name: request.refresh_token
for request in requests
if request.refresh_token is not None
},
)
connections = await connect_mcp_servers([request.config for request in requests])
for connection in connections:
request = request_by_name[connection.name]
registry.add(
@@ -407,6 +391,5 @@ async def attach_mcp_requests(
purpose=request.purpose or connection.notes,
provider=request.provider,
result_transform=request.result_transform,
refresh_token=request.refresh_token,
)
return connections
+1 -9
View File
@@ -129,20 +129,12 @@ def classify(exc: BaseException) -> FailureInfo:
class HttpStatusRecorder:
"""Capture the last non-success response from one HTTP connection.
A later success clears a recorded 401, so a bearer refreshed and retried
in the auth flow does not leave a stale auth failure behind.
"""
"""Capture the last non-success response from one HTTP connection."""
def __init__(self) -> None:
self._failure: FailureInfo | None = None
async def __call__(self, response: httpx.Response) -> None:
if 200 <= response.status_code < 300:
if self._failure is not None and self._failure.kind == "auth":
self._failure = None
return
if not 200 <= response.status_code < 300:
request = response.request
self._failure = _from_status(
+2 -13
View File
@@ -32,7 +32,7 @@ from strix.tools.mcp.session import McpConnectionUnavailableError, SupervisedMcp
if TYPE_CHECKING:
from collections.abc import Awaitable, Callable
from collections.abc import Callable
from agents.mcp import MCPServer
@@ -96,9 +96,6 @@ class McpConnectionEntry:
tool_count: int = 0
result_transform: ResultTransform | None = None
provider: str | None = None
refresh_token: Callable[[], Awaitable[str | None]] | None = dataclasses.field(
default=None, repr=False
)
state: McpConnectionState = "configured"
_catalog: list[Any] | None = dataclasses.field(default=None, repr=False)
_connect_task: asyncio.Task[SupervisedMcpSession] | None = dataclasses.field(
@@ -183,7 +180,7 @@ class McpConnectionEntry:
f"MCP connection {self.name!r} has no connection configuration."
)
self._set_state("connecting")
session = SupervisedMcpSession(config, refresh_token=self.refresh_token)
session = SupervisedMcpSession(config)
try:
started = await session.start()
except BaseException:
@@ -301,17 +298,12 @@ class McpConnectionRequest:
at the single dispatch point (strix-pro's sanitizer; empty for the
command-line path). ``purpose`` is the human label ``list_mcps`` reports as the
connection's description; when unset it falls back to ``config.notes``.
``refresh_token`` optionally fetches a new bearer asynchronously after an HTTP
401; returning no token or the current token leaves the failure unchanged.
"""
config: McpConnectionConfig
provider: str | None = None
result_transform: ResultTransform | None = None
purpose: str | None = None
refresh_token: Callable[[], Awaitable[str | None]] | None = dataclasses.field(
default=None, repr=False
)
class McpCallInfo(NamedTuple):
@@ -345,7 +337,6 @@ class McpRegistry:
purpose=request.purpose or request.config.notes,
result_transform=request.result_transform,
provider=request.provider,
refresh_token=request.refresh_token,
)
entry.set_status_sink(self._status_sink)
self._entries[entry.name] = entry
@@ -362,7 +353,6 @@ class McpRegistry:
tool_count: int = 0,
result_transform: ResultTransform | None = None,
provider: str | None = None,
refresh_token: Callable[[], Awaitable[str | None]] | None = None,
) -> McpConnectionEntry:
"""Register one connection under ``name`` (last write wins).
@@ -384,7 +374,6 @@ class McpRegistry:
tool_count=tool_count,
result_transform=result_transform,
provider=provider,
refresh_token=refresh_token,
state="connected",
)
entry.set_status_sink(self._status_sink)
+2 -18
View File
@@ -54,7 +54,6 @@ import time
import weakref
from typing import TYPE_CHECKING, Any, Literal, cast
from strix.tools.mcp.auth import RefreshingBearerAuth
from strix.tools.mcp.config import DEFAULT_MAX_CONCURRENT_CALLS
from strix.tools.mcp.failures import FailureInfo, HttpStatusRecorder, classify
@@ -158,19 +157,9 @@ class SupervisedMcpSession:
:attr:`name`, :attr:`server`, :attr:`config`, :attr:`is_dead`.
"""
def __init__(
self,
config: McpConnectionConfig,
*,
refresh_token: Callable[[], Awaitable[str | None]] | None = None,
) -> None:
def __init__(self, config: McpConnectionConfig) -> None:
self._name = config.name
self._config: McpConnectionConfig | None = config
self._bearer_auth = (
RefreshingBearerAuth(config.auth.token if config.auth else None, refresh_token)
if refresh_token is not None and config.transport == "http"
else None
)
self._server: MCPServer | None = None
self._supervised = True
self._task: asyncio.Task[None] | None = None
@@ -204,7 +193,6 @@ class SupervisedMcpSession:
self = cls.__new__(cls)
self._name = name
self._config = config
self._bearer_auth = None
self._server = server
self._supervised = False
self._task = None
@@ -713,11 +701,7 @@ class SupervisedMcpSession:
if self._config is None:
raise RuntimeError(f"MCP connection {self._name!r} has no config to connect")
built = (
_build_server(self._config, self._bearer_auth)
if self._bearer_auth is not None
else _build_server(self._config)
)
built = _build_server(self._config)
server = built.server
self._recorder = built.recorder
try:
+12 -2
View File
@@ -1693,6 +1693,7 @@ _VALID_REACHABILITY = frozenset(
{
"not_imported",
"imported",
"not_reached",
"vulnerable_symbol_used",
"reachable_call_path",
"unknown",
@@ -1840,6 +1841,9 @@ def _build_dependency_metadata(
_REACHABILITY_EVIDENCE_LABELS = {
"not_imported": "not imported by application code",
"imported": "imported by application code; affected API usage unconfirmed",
"not_reached": (
"imported by application code; the vulnerable code of this advisory is not reached"
),
"vulnerable_symbol_used": "the advisory's affected API is used in application code",
"reachable_call_path": (
"a call path from application code to the vulnerable function was proven"
@@ -2157,6 +2161,11 @@ async def create_dependency_report(
can evade static search).
- ``imported`` — application code imports the package, but usage of
the advisory's affected API was not confirmed.
- ``not_reached`` — application code imports the package, and the
analysis showed that the vulnerable code of this advisory does not
run here (the affected API has no caller, the only call site is
behind a condition that is false in this codebase, the parent
package never reaches it, ...). Per advisory, never per package.
- ``vulnerable_symbol_used`` — the advisory's affected
function/class/API appears in application code.
- ``reachable_call_path`` — a call-graph tool (e.g. ``govulncheck``)
@@ -2210,8 +2219,9 @@ async def create_dependency_report(
repository root. This binds the finding to its exact file so
remediation can target the right repository.
reachability: Usage-evidence level from static analysis — one of
``not_imported`` / ``imported`` / ``vulnerable_symbol_used`` /
``reachable_call_path`` / ``unknown``. Claim only what the
``not_imported`` / ``imported`` / ``not_reached`` /
``vulnerable_symbol_used`` / ``reachable_call_path`` /
``unknown``. Claim only what the
evidence proves; when in doubt use ``unknown``.
reachability_evidence: **Required.** The concrete proof for the
claimed level, or, for ``unknown``, what you searched and why
-223
View File
@@ -1,223 +0,0 @@
"""HTTP bearer refresh regressions without network access."""
from __future__ import annotations
import asyncio
from typing import Any, cast
from unittest.mock import AsyncMock
import httpx
import pytest
from mcp.types import CallToolResult, TextContent, Tool
from strix.tools.mcp import BearerAuth, McpConnectionConfig, McpConnectionRequest, McpRegistry
from strix.tools.mcp import client as mcp_client
from strix.tools.mcp import session as mcp_session
from strix.tools.mcp.auth import RefreshingBearerAuth
def _config() -> McpConnectionConfig:
return McpConnectionConfig(
name="refresh",
url="https://example.test/mcp",
auth=BearerAuth(token="old"), # noqa: S106 # nosec B106
)
def _client(auth: RefreshingBearerAuth | None, handler: Any) -> httpx.AsyncClient:
built = mcp_client._build_server(_config(), auth)
params = cast("Any", built.server).params
assert params["headers"] == ({} if auth else {"Authorization": "Bearer old"})
client = cast("httpx.AsyncClient", params["httpx_client_factory"](headers=params["headers"]))
client._transport = httpx.MockTransport(handler)
return client
@pytest.mark.asyncio
async def test_refresh_retries_once_and_persists_across_server_builds() -> None:
refresh = AsyncMock(return_value="new")
session = mcp_session.SupervisedMcpSession(_config(), refresh_token=refresh)
seen: list[str] = []
def handler(request: httpx.Request) -> httpx.Response:
seen.append(request.headers["Authorization"])
return httpx.Response(200 if seen[-1] == "Bearer new" else 401)
for _ in range(2):
async with _client(session._bearer_auth, handler) as client:
response = await client.post("https://example.test/mcp", content=b"payload")
assert response.status_code == 200
assert seen == ["Bearer old", "Bearer new", "Bearer new"]
refresh.assert_awaited_once()
@pytest.mark.asyncio
@pytest.mark.parametrize("replacement", ["new", None, "old", "raises"])
async def test_concurrent_unauthorized_requests_share_refresh(replacement: str | None) -> None:
refresh = AsyncMock(return_value=replacement)
if replacement == "raises":
refresh.side_effect = ValueError("refresh unavailable")
auth = RefreshingBearerAuth("old", refresh)
both_sent = asyncio.Event()
old_requests = 0
async def handler(request: httpx.Request) -> httpx.Response:
nonlocal old_requests
if request.headers["Authorization"] == "Bearer old":
old_requests += 1
if old_requests == 5:
both_sent.set()
await both_sent.wait()
return httpx.Response(401)
return httpx.Response(200)
async with _client(auth, handler) as client:
responses = await asyncio.wait_for(
asyncio.gather(*(client.get("https://example.test/mcp") for _ in range(5))),
timeout=2,
)
assert [response.status_code for response in responses] == [
200 if replacement == "new" else 401
] * 5
assert old_requests == 5
refresh.assert_awaited_once()
@pytest.mark.parametrize("replacement", [None, "", "old", "new", "raises", "disabled"])
@pytest.mark.asyncio
async def test_unrecovered_401_still_retires_connection(
replacement: str | None, caplog: pytest.LogCaptureFixture
) -> None:
refresh = AsyncMock(return_value=replacement)
if replacement == "raises":
refresh.side_effect = ValueError("private-token-value")
auth = None if replacement == "disabled" else RefreshingBearerAuth("old", refresh)
seen: list[str] = []
def handler(request: httpx.Request) -> httpx.Response:
seen.append(request.headers["Authorization"])
return httpx.Response(401)
async with _client(auth, handler) as client:
server = AsyncMock()
async def call_tool(*_args: Any, **_kwargs: Any) -> None:
response = await client.get("https://example.test/mcp")
response.raise_for_status()
server.call_tool = call_tool
session = mcp_session.SupervisedMcpSession.adopt(server, name="refresh")
result = await session.dispatch("read", {}, label="refresh_read")
assert result["success"] is False
assert session.is_dead
await session.aclose()
assert seen == (["Bearer old", "Bearer new"] if replacement == "new" else ["Bearer old"])
assert refresh.await_count == (0 if replacement == "disabled" else 1)
assert "private-token-value" not in caplog.text
if replacement == "raises":
assert "ValueError" in caplog.text
@pytest.mark.asyncio
async def test_non_401_does_not_refresh() -> None:
refresh = AsyncMock(return_value="new")
auth = RefreshingBearerAuth("old", refresh)
async with _client(auth, lambda _: httpx.Response(403)) as client:
assert (await client.get("https://example.test/mcp")).status_code == 403
refresh.assert_not_awaited()
@pytest.mark.asyncio
async def test_registry_passes_refresher_to_session(monkeypatch: pytest.MonkeyPatch) -> None:
refresh = AsyncMock(return_value="new")
registry = McpRegistry()
entry = registry.register(McpConnectionRequest(_config(), refresh_token=refresh))
server = AsyncMock()
captured: list[RefreshingBearerAuth] = []
def build(_config: McpConnectionConfig, auth: RefreshingBearerAuth) -> Any:
captured.append(auth)
return mcp_client.BuiltMcpServer(server, None)
monkeypatch.setattr(mcp_client, "_build_server", build)
session = await entry.ensure_connected()
assert entry.refresh_token is refresh
assert captured == [session._bearer_auth]
await session._open()
assert captured == [session._bearer_auth, session._bearer_auth]
await session.aclose()
@pytest.mark.asyncio
async def test_refreshed_token_can_refresh_again_after_expiry() -> None:
refresh = AsyncMock(side_effect=["new", "newer"])
auth = RefreshingBearerAuth("old", refresh)
valid = "new"
def handler(request: httpx.Request) -> httpx.Response:
return httpx.Response(200 if request.headers["Authorization"] == f"Bearer {valid}" else 401)
async with _client(auth, handler) as client:
assert (await client.get("https://example.test/mcp")).status_code == 200
valid = "newer"
assert (await client.get("https://example.test/mcp")).status_code == 200
assert refresh.await_count == 2
@pytest.mark.parametrize("with_refresher", [True, False])
@pytest.mark.asyncio
async def test_eager_attachment_preserves_bearer_refresh(
monkeypatch: pytest.MonkeyPatch, with_refresher: bool
) -> None:
refresh = AsyncMock(return_value="new")
original_build = mcp_client._build_server
valid = "old"
def handler(request: httpx.Request) -> httpx.Response:
return httpx.Response(200 if request.headers["Authorization"] == f"Bearer {valid}" else 401)
def build(config: McpConnectionConfig, auth: RefreshingBearerAuth | None = None) -> Any:
built = original_build(config, auth)
params = cast("Any", built.server).params
client = params["httpx_client_factory"](headers=params["headers"])
client._transport = httpx.MockTransport(handler)
server = AsyncMock()
server.use_structured_content = False
server.list_tools.return_value = [Tool(name="read", inputSchema={"type": "object"})]
server.cleanup.side_effect = client.aclose
async def call_tool(*_args: Any, **_kwargs: Any) -> CallToolResult:
response = await client.post("https://example.test/mcp")
response.raise_for_status()
return CallToolResult(content=[TextContent(type="text", text="ok")])
server.call_tool = call_tool
return mcp_client.BuiltMcpServer(server, built.recorder)
monkeypatch.setattr(mcp_client, "_build_server", build)
registry = McpRegistry()
try:
connections = await mcp_client.attach_mcp_requests(
[McpConnectionRequest(_config(), refresh_token=refresh if with_refresher else None)],
registry,
)
assert len(connections) == 1
entry = registry.get("refresh")
assert entry is not None
assert entry.refresh_token is (refresh if with_refresher else None)
session = await entry.ensure_connected()
assert await session.dispatch("read", {}, label="refresh_read") == {
"type": "text",
"text": "ok",
}
valid = "new"
result = await session.dispatch("read", {}, label="refresh_read")
if with_refresher:
assert result == {"type": "text", "text": "ok"}
assert not session.is_dead
refresh.assert_awaited_once()
else:
assert result["success"] is False
assert session.is_dead
finally:
await registry.close()
-9
View File
@@ -111,15 +111,6 @@ async def test_retry_after_parses_seconds_and_http_date() -> None:
assert 0 <= retry_after <= 20
@pytest.mark.asyncio
async def test_successful_response_clears_previous_auth_failure() -> None:
recorder = HttpStatusRecorder()
await recorder(_http_error(401).response)
request = httpx.Request("POST", "https://provider.example/tools")
await recorder(httpx.Response(200, request=request))
assert recorder.take() is None
@pytest.mark.asyncio
async def test_recorder_only_keeps_non_sensitive_request_metadata() -> None:
recorder = HttpStatusRecorder()
+33
View File
@@ -668,6 +668,39 @@ async def test_dependency_report_records_reachability(report_state: ReportState)
assert report["severity"] == "high"
async def test_dependency_report_records_not_reached(report_state: ReportState) -> None:
result = await _do_create_dependency(
title="CVE-2021-23337 in lodash 4.17.20",
description="Command injection via template.",
target="repo/package.json",
cve="CVE-2021-23337",
package_name="lodash",
installed_version="4.17.20",
impact="Command injection where template is used.",
remediation_steps="Upgrade to 4.17.21.",
assumptions="Static search only; no dynamic dispatch into lodash was found.",
package_ecosystem="npm",
manifest_path="package-lock.json",
fixed_version="4.17.21",
cwe=None,
advisory_cvss=7.2,
technical_analysis=None,
fix_effort="low",
reachability="not_reached",
reachability_evidence=(
"src/util/strings.ts:3 imports lodash; a complete search of src/ finds no "
"call to _.template, the only API the advisory affects."
),
contextual_cvss_breakdown=_DEP_CONTEXT,
contextual_cvss_reasoning=_DEP_REASONING,
)
assert result["success"] is True
report = report_state.vulnerability_reports[0]
assert report["dependency_metadata"]["reachability"] == "not_reached"
assert "the vulnerable code of this advisory is not reached" in report["evidence"]
async def test_dependency_report_rejects_reachability_without_evidence(
report_state: ReportState,
) -> None: