attackmap 0.2.0__tar.gz → 0.3.1__tar.gz

{attackmap-0.2.0/src/attackmap.egg-info → attackmap-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.2.0
+Version: 0.3.1
 Summary: AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints.
 Author: AttackMap Contributors
 Author-email: Matthew Davis <matthewd@matthewd.xyz>
@@ -60,9 +60,11 @@ Dynamic: license-file
 # AttackMap
 
 **AI-assisted defensive security analysis for codebases.** AttackMap reads your
-repository, models its assets and defensive controls, finds cross-cutting
-weaknesses that single-file scanners miss, and produces an evidence-grounded
-security review with MITRE ATT&CK mappings and detection-engineering hints.
+repository, models its assets and defensive controls, traces request-to-sink
+data flow, inventories dependencies and their known CVEs, and produces an
+evidence-grounded security review with MITRE ATT&CK mappings and
+detection-engineering hints — finding the cross-cutting weaknesses that
+single-file scanners miss.
 
 Built for AppSec engineers, SOC and detection-engineering teams, and engineering
 managers who need to triage an unfamiliar codebase.
@@ -71,6 +73,13 @@ managers who need to triage an unfamiliar codebase.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/attackmap.svg)](https://pypi.org/project/attackmap/)
+
+> **Status: beta (v0.3.1).** Core engine and 14 analyzer plugins are published
+> to PyPI, Homebrew, and GHCR and validated against real-world codebases.
+> AttackMap is heuristic by design — findings are confidence-tiered evidence,
+> not proof. See [Project status](#project-status) for what's solid and what's
+> still maturing.
 
 ---
 
@@ -108,7 +117,7 @@ Read `reports/defensive-review.md` (heuristic) and `reports/defensive-review-llm
 ```bash
 pip install attackmap                  # core only
 pip install "attackmap[llm]"           # add LLM narrative support
-pip install "attackmap[all]"           # core + LLM + all 13 analyzer plugins
+pip install "attackmap[all]"           # core + LLM + all 14 analyzer plugins
 ```
 
 You can also install individual analyzer plugins on demand:
@@ -166,8 +175,10 @@ Every `attackmap analyze` run writes:
 | `attackmap-paths.md` | Mermaid flowcharts of each attack path — renders inline on GitHub |
 | `attackmap-topology.md` | Mermaid graph of the service topology, with edge kinds styled per relationship type |
 | `attackmap-paths.dot` / `attackmap-topology.dot` | Graphviz DOT versions of the two diagrams — feed into `dot -Tsvg` for slide-quality graphics |
+| `attackmap-exploitability.md` | "Most exploitable now" — route→sink paths ranked by fused 0–100 score, each with its factors |
 | `defensive-review-llm.md` *(with `--llm`)* | Claude-narrated review |
 | `defensive-review-llm.meta.json` *(with `--llm`)* | Backend, model, token usage |
+| `vulnerability-hypotheses.md` *(with `--hunt`)* | LLM-generated, evidence-cited exploit-chain **hypotheses** to confirm (leads, not detections) |
 
 ### GitHub Code Scanning integration
 
@@ -213,6 +224,151 @@ on unrelated commits, so a finding that persists across scans has the same id
 in both. The diff has three sections — **New**, **Persisted**, **Resolved** —
 which drop cleanly into a PR comment.
 
+### Data-flow / injection detection
+
+A lightweight taint pass (Python + JS/TS) walks the import graph up to two hops
+from each route handler and flags dangerous sinks reachable from an entry point.
+Each sink kind that a route can reach produces a dedicated finding with an
+ATT&CK mapping:
+
+| Sink kind | What it catches | Severity |
+|---|---|---|
+| `eval` / `exec` | Request-reachable code execution | HIGH |
+| `subprocess_shell` | OS command execution (`shell=True`, `child_process.exec`) | HIGH |
+| `unsafe_deserialization` | `pickle.loads`, `yaml.load` (no SafeLoader), `marshal`, `node-serialize` | HIGH |
+| `ssti` | Server-side template injection (`render_template_string`, `Template(req…)`) | HIGH |
+| `ssrf` | Request-derived URL into `requests`/`httpx`/`urlopen`/`axios`/`fetch` | MEDIUM |
+| `nosql_injection` | Request object as a Mongo filter, or `$where` | MEDIUM |
+| `sql_execute` | Cursor/session `.execute`/`.query` reachable from a route | (feeds attack paths) |
+| `dynamic_open` | `open()` with request-shaped path | (feeds attack paths) |
+
+| `open_redirect` | Request-derived URL into `redirect()`/`res.redirect()` | MEDIUM |
+
+Beyond the taint sinks, a per-file pass flags additional undisclosed-vuln
+classes (`scan.code_weaknesses`): **prototype pollution** (`__proto__` writes,
+deep-merge of a request object), **mass assignment** (a whole request body bound
+to a model), **JWT weaknesses** (`alg=none`, signature verification off), **XXE**
+(XML parsers with external entities enabled), **ReDoS** (regexes with
+catastrophic backtracking), **insecure upload** (a file saved under a
+client-controlled name/path), and **GraphQL exposure** (introspection/playground
+left on).
+
+Sinks that are only dangerous with attacker-controlled input (SSRF, SSTI, NoSQL,
+open redirect, `open`) are gated on a request-shaped identifier in the call — a constant URL or
+template is not flagged. It's a heuristic (import-edge ≠ call-edge), so findings
+are evidence, not proof; confidence tapers with hop distance. Chains appear in
+`attackmap-report.json` under `scan.taint_chains`.
+
+Test and spec files (`tests/`, `__tests__/`, `*.test.*`, `test_*.py`, …) are
+excluded from all the heuristic passes above by default, since dangerous
+patterns in test scaffolding are rarely real exposure. Set
+`ATTACKMAP_INCLUDE_TESTS=1` to scan them too (e.g. for test-quality reviews).
+
+### Web hardening gaps
+
+Route- and config-level checks for common web misconfigurations, each an
+ATT&CK-mapped finding:
+
+| Kind | Catches | Severity |
+|---|---|---|
+| `cors_wildcard_credentials` | wildcard/reflected CORS origin **with** credentials | HIGH |
+| `csrf_disabled` | CSRF explicitly disabled / exempted | MEDIUM |
+| `insecure_cookie` | `httpOnly:false`, `secure:false`, `SameSite=None` without `Secure` | MEDIUM |
+| `weak_csp` | CSP allowing `'unsafe-inline'` / `'unsafe-eval'` | MEDIUM |
+| `debug_enabled` | debug mode / actuator wildcard exposure shipped on | MEDIUM |
+
+These detect *positively-present* misconfigurations rather than hard-to-judge
+absences (a wildcard CORS origin alone is fine — it's the pairing with
+credentials that's flagged). Results appear under `scan.web_hardening_issues`.
+
+### Insecure cryptography & weak randomness
+
+A cheap per-file pass flags crypto misuse, each as a finding with an ATT&CK
+mapping:
+
+| Kind | Catches | Severity |
+|---|---|---|
+| `weak_password_hash` | MD5/SHA-1 over a password-shaped value | HIGH |
+| `weak_cipher` | DES / 3DES / RC4 / Blowfish | HIGH |
+| `ecb_mode` | ECB block-cipher mode (incl. Java's `Cipher.getInstance("AES")` default) | MEDIUM |
+| `static_iv_salt` | hard-coded IV or salt literal | MEDIUM |
+| `insecure_random` | `Math.random`/`random`/`rand`/`mt_rand` for a token/key/salt/nonce | MEDIUM |
+| `insecure_tls` | `verify=False`, `rejectUnauthorized:false`, `InsecureSkipVerify:true`, deprecated TLS | HIGH |
+
+The noisy families (weak hash, insecure RNG) are gated on a security-context
+identifier; cipher/ECB tokens are matched case-sensitively so algorithm names
+aren't confused with prose (e.g. the French word "des"). Results appear under
+`scan.crypto_weaknesses`.
+
+### Broken object-level authorization (BOLA / IDOR)
+
+OWASP API Security #1. AttackMap flags a route as a BOLA/IDOR candidate when it
+composes three signals it already has:
+
+1. the route takes a **resource id** in the path (`/users/{id}`,
+   `/orders/:orderId`, `/docs/<int:doc_id>`), and
+2. it **reaches a datastore** — a DB hint in the same file/module, or a taint
+   chain from the route to a SQL execute sink, and
+3. **no ownership/authorization check** is visible near the handler
+   (`current_user`, `request.user`, `authorize`, a policy/guard, or a
+   `filter_by(user_id=…)`-style scoped query).
+
+Write routes (POST/PUT/PATCH/DELETE) are HIGH, reads MEDIUM. Candidates appear
+under `scan.authz_candidates`; the ownership-marker scan is the main
+false-positive reducer, so a well-scoped handler is not flagged. Path-template
+routes today; query-parameter and RPC-method ids are future work.
+
+### Anomaly / outlier detection
+
+The closest honest thing to "surface the unknown": instead of matching a
+known-bad signature, AttackMap flags a route that deviates from the norm its own
+siblings establish. Routes are bucketed into resource cohorts by path prefix
+(`/api/users`, `/api/users/{id}` and `/api/users/export` all share `api/users`;
+`api`/version scaffolding is stripped so versioned resources still separate), and
+within each cohort the odd-one-out is reported:
+
+| Kind | Catches | Severity |
+|---|---|---|
+| `auth_outlier` | siblings carry an auth/authorization signal near the handler; this route doesn't | HIGH |
+| `validation_outlier` | among a cohort's state-changing handlers, peers validate input and this one shows no validation marker | LOW |
+| `method_outlier` | a lone state-changing method in an otherwise read-only cohort | MEDIUM |
+
+Everything is peer-relative and **confidence scales with how consistent the
+cohort is** — a lone deviation among many agreeing siblings is likelier a mistake
+than the same deviation in a split group. Outliers are only flagged when they're a
+strict minority (a genuinely 50/50 surface isn't nagged), the cohort must have
+real route structure (distinct paths with parameters/sub-paths, not repeated
+method-call strings), and per-route signal detection is scoped to each handler's
+own span so a sibling's guard is never miscredited. Results appear under
+`scan.anomalies`, each finding naming the peer group and the deviation. This is
+the scan-level, route-cohort counterpart to the layered engine's
+`asymmetric_protection` insight.
+
+### Exploitability fusion ("Most exploitable now")
+
+Every signal AttackMap has about a route→sink path is fused into a single
+**0–100 exploitability score** so the highest-risk *combinations* rise to the
+top — the public, unauthenticated route whose request reaches a SQL sink next to
+a secret is a different animal from an internal, authed route that reaches the
+same sink two hops away. The score is:
+
+- **Deterministic** — the same scan always yields the same number; no
+  randomness, no clock.
+- **Explainable** — the score is the clamped sum of named factors, and every one
+  is shown. Contributing factors: sink danger (SQLi/RCE/deserialization highest),
+  exposure (public/internal/unknown), auth at the entry route, reachability
+  (fewer hops = higher), and data sensitivity at the sink (a co-located secret or
+  datastore), plus insecure-crypto / web-hardening gaps on the path as
+  amplifiers.
+
+Scores land on the relevant taint findings (`exploitability` + `exploitability_tier`)
+and in a ranked **`attackmap-exploitability.md`** report plus the `exploitability`
+array in `attackmap-report.json`; the console summary leads with the top few. For
+example, `public + no-auth + taint-to-eval (0 hops)` scores 90/100 (CRITICAL).
+(Dependency CVEs are manifest-level, not attributable to a specific source path,
+so they inform the report but aren't folded into a path's score — path-attributed
+CVE fusion is future work.)
+
 ### SBOM inventory
 
 Every scan also produces a lightweight SBOM by parsing direct dependencies out
@@ -268,7 +424,10 @@ AttackMap is built as four layers, each grounded in the layer below.
 databases, external calls, auth signals, secrets, frameworks, and entrypoints.
 Every signal carries a `file:line` citation, an evidence-text snippet, and a
 confidence score. Plugins are auto-discovered through the `attackmap.analyzers`
-entry-point group.
+entry-point group. Alongside recon, three cross-file passes run in core: a
+**taint / data-flow** walk (request-to-sink reachability across imports), a
+**BOLA/IDOR** authorization check, and an **SBOM** dependency inventory
+(optionally cross-referenced against OSV.dev with `--cve`).
 
 **2. Asset and control overlay.** Identifies *what's at risk* (credentials,
 sessions, PII, payment records, internal secrets — with criticality tiers) and
@@ -285,6 +444,18 @@ trust-boundary violations, and more.
 from the structured evidence pack. The model is forced to cite real
 surface/asset/control IDs, so it can't invent findings.
 
+**5. Vulnerability-hypothesis hunting (`--hunt`).** The honest core of the
+"find the unknown" ask. `attackmap analyze . --hunt` has Claude reason over the
+full evidence pack (surfaces, assets, controls, taint chains, exploitability
+scores, anomalies) as a red-team analyst and propose **ranked, human-verifiable
+exploit-chain hypotheses** — candidate weaknesses a static rule wouldn't catch,
+especially novel cross-signal combinations. Output goes to
+`vulnerability-hypotheses.md` under an unmissable banner: **these are hypotheses
+to confirm, not detections.** The same grounding contract as the review applies
+(every hypothesis cites real evidence IDs), plus honesty guardrails: no CVE
+assignment, no exploit code, confidence-tiered, and each lead lists exactly what
+a human must verify. Uses the same auth/backend resolution as `--llm`.
+
 Layered on top: **MITRE ATT&CK technique mappings** on every insight and
 **detection opportunities** (Sigma/KQL/Splunk-style hints) for each weakness.
 
@@ -292,7 +463,7 @@ Layered on top: **MITRE ATT&CK technique mappings** on every insight and
 
 ## Supported ecosystems
 
-Thirteen official analyzer plugins, each distributable as a separate package:
+Fourteen official analyzer plugins, each distributable as a separate package:
 
 | Plugin | Coverage |
 |---|---|
@@ -302,13 +473,15 @@ Thirteen official analyzer plugins, each distributable as a separate package:
 | `attackmap-analyzer-java-spring` | Java/Kotlin Spring Boot, JAX-RS, Ktor; Spring Data; Spring Security; jjwt |
 | `attackmap-analyzer-dotnet` | ASP.NET Core minimal APIs and attribute routing, EF Core, Identity, JwtBearer |
 | `attackmap-analyzer-terraform` | AWS, Azure, GCP resources; IAM wildcards; open SGs; secrets |
+| `attackmap-analyzer-iac` | Dockerfile hardening, docker-compose service graphs, GitHub Actions workflows, `.env` templates, shell installers |
 | `attackmap-analyzer-c` | libmicrohttpd, civetweb, mongoose; libcurl; OpenSSL/libsodium; sqlite3/libpq/mysql |
 | `attackmap-analyzer-cpp` | Crow, Pistache, Drogon, cpprestsdk; libcurl/cpr; OpenSSL/Botan/libsodium; libpqxx/mongocxx |
 | `attackmap-analyzer-node-service` | Node.js / TypeScript service ecosystems |
 | `attackmap-analyzer-atproto` | AT Protocol (Bluesky) services |
 | `attackmap-analyzer-php-web` / `-php-laminas` / `-omeka-s` | Generic PHP web, Laminas/Zend MVC, Omeka-S |
 
-`pip install "attackmap[all]"` installs every official plugin.
+`pip install "attackmap[all]"` installs every official plugin. Not sure which
+you need? `attackmap suggest ./repo` recommends the right set for a repo's shape.
 
 ### Building your own analyzer
 
@@ -324,16 +497,28 @@ scaffolding, testing, and publishing instructions is in
 ```bash
 attackmap analyze <path>                 # run a review on a repository
 attackmap analyze <path> --output dir    # write outputs to `dir/`
+attackmap analyze <path> --format json   # json | markdown | all (default)
 attackmap analyze <path> --module python --module rust   # only these analyzers
+attackmap analyze <path> --cve           # cross-reference SBOM against OSV.dev
 attackmap analyze <path> --llm           # add LLM narrative (auto-resolve auth)
 attackmap analyze <path> --llm --llm-backend cli         # force Claude CLI
+attackmap analyze <path> --hunt          # LLM vulnerability-hypothesis hunt (leads to confirm)
+
+# CI / PR diff gating
+attackmap analyze <path> --baseline prev/attackmap-report.json \
+  --diff-output reports/attackmap-diff.md --fail-on-new-high
+
+# Plugin discovery
 attackmap suggest ./repo                 # recommend plugins for a repo shape
 attackmap suggest ./repo --install       # and pip-install the missing ones
 attackmap modules                        # list installed analyzers
 ```
 
 `--module` is repeatable. Missing requested external analyzers can be
-auto-installed (when possible) from the `mlaify` GitHub organization.
+auto-installed (when possible) from the `mlaify` GitHub organization. `--cve`
+does network I/O (cached under `~/.attackmap/cache/osv/`, 24h TTL);
+`--fail-on-new-high` requires `--baseline` and exits non-zero when the diff
+introduces a new HIGH finding.
 
 ---
 
@@ -341,13 +526,61 @@ auto-installed (when possible) from the `mlaify` GitHub organization.
 
 - **A runtime detector.** AttackMap is static. The detection opportunities it
   emits are *hints* for your SIEM team — they are not deployable rules.
-- **A vulnerability scanner.** AttackMap models architecture, assets, and
-  controls. It does not match known-CVE patterns.
+- **A replacement for dedicated SCA.** AttackMap does inventory dependencies and
+  cross-reference OSV.dev with `--cve`, but tools like Trivy, Grype, and
+  Dependabot go deeper on transitive resolution and lockfiles. AttackMap's
+  value is folding the CVE signal into an architecture-aware narrative
+  ("this public route reaches this vulnerable ORM").
+- **A true taint engine.** The data-flow pass is a heuristic import-graph walk
+  (import-edge ≈ call-edge), not sound interprocedural taint analysis. It
+  favors precision over recall; findings are evidence, not proof.
 - **Exhaustive.** AttackMap is heuristic by design. Findings are confidence-tiered
   with explicit guardrails for stale signals.
 
 ---
 
+## Project status
+
+AttackMap is **beta** (v0.3.1) — published and validated on real codebases, but
+pre-1.0 and heuristic.
+
+**Solid today:**
+
+- Modular analyzer execution with entry-point discovery; 14 official plugins on PyPI.
+- Framework-aware route extraction (FastAPI/Flask/Express/Spring/axum/chi/…).
+- Asset + control modeling, cross-cutting insight engine, chain-aware threat model.
+- Injection / data-flow detection: SSRF, SSTI, NoSQL, unsafe deserialization,
+  eval/exec/shell, SQL, dynamic file open, open redirect — request-container-gated
+  for precision.
+- Novel vuln-class detectors: prototype pollution, mass assignment, JWT weakness,
+  XXE, ReDoS, insecure upload, GraphQL exposure.
+- BOLA/IDOR authorization detection on path-template routes.
+- Insecure-crypto / weak-randomness and web-hardening (CORS/CSRF/cookies/CSP/debug)
+  detection.
+- Anomaly / outlier detection (the odd-one-out among sibling routes) and
+  **exploitability fusion** — a deterministic, explainable 0–100 "exploitable now"
+  score that ranks route→sink combinations.
+- **`--hunt`**: LLM vulnerability-hypothesis mode — evidence-cited, human-verifiable
+  exploit-chain leads (not detections).
+- SBOM inventory (5 ecosystems) + OSV.dev CVE cross-reference (`--cve`).
+- Output: Markdown + JSON + **SARIF 2.1.0** (GitHub Code Scanning) + **Mermaid /
+  Graphviz** diagrams; **diff/baseline** mode for PR gating; optional LLM narrative.
+- Live scan progress bar + ETA; test/spec files excluded from heuristic passes.
+- Distribution: `pip install attackmap[all]`, `brew install mlaify/tap/attackmap`,
+  `docker pull ghcr.io/mlaify/attackmap`.
+
+**Still maturing:**
+
+- Taint + BOLA are Python + JS/TS and path-template scoped; query-param / RPC-method
+  authorization and more languages are planned.
+- The import-graph taint walk approximates call-edges with import-edges — precision
+  over recall; findings are evidence, not proof.
+- CVE lookup resolves a best-effort concrete version, not full lockfile ranges, and
+  isn't yet fused into per-path exploitability scores.
+- Anomaly / exploitability reasoning is route-cohort and taint-chain scoped.
+
+---
+
 ## Documentation
 
 - [`CHANGELOG.md`](CHANGELOG.md) — release notes