habiregottenzartto - Deterministic, reachability-aware software composi

项目说明

habiregottenzartto

Deterministic, reachability-aware supply-chain intelligence engine.

![CI]()
!Python
!License
!Runtime deps
!Tests

Most dependency scanners answer *"do you have a package with a known CVE?"* and
hand you a wall of 2,000 findings. habiregottenzartto answers the question a
security engineer actually asks:

> *"Which of these is in a I really run, in code my
> program really reaches, that attackers are really exploiting — and prove it."*

It is local-first, air-gap capable, has zero runtime dependencies,
and every carries a machine-checkable e chain.

---

Why this exists (and how it leapfrogs C)

C is a commodity (pip-audit, os, Trivy all do it). The
frontier — what Snyk and Endor Labs charge enterprise money for — is **cutting
the noise and proving exploitability**. This engine ships that frontier in
v0.1:

| Capability | Commodity SCA | habiregottenzartto |
|---|---|---|
| source | often guesses from imports | lockfile-first; ne a guessed |
| comparison | lexical / library | self-contained PEP 440 engine (epochs, pre/post/de) |
| Result | "you ha" | risk = se × threat-intel × reachability × confidence |
| Noise control | none | function-le → unreachable 9.8 becomes LOW |
| Affected-symbol data | hand-curated ( moat) | auto-mined from fixing-commit patches |
| Reachability precision | package presence | call-graph path to the function, printed |
| Cross-package analysis | — | descends into dependency internals to pro the sink path |
| Exploitability | — | EPSS + KEV enrichment, OpenVEX not_affected output |
| Threats without a CVE | missed | typosquat / supply-chain heuristics |
| "Why did you flag this?" | — | e DAG in the terminal |
| Reproducibility | — | content-hashed DB snapshot, replayable scans |

---

Quickstart

No network. No pip install required to try it — pure standard library
(tomllib, ast, sqlite3). Python ≥ 3.11.

---

The demo, annotated

examples/demo-project pins old, genuinely- . One scan shows
the whole thesis:

pyyaml — REACH:SYM. The call graph proves a path to the affected

function and --explain prints it:
app.main:<toplevel> → app.main.run → app.config.load_config → pyyaml.full_load.
Symbol-confirmed exposure → ranked top.

requests — reach:indirect. The code calls requests.get, but the

functions (rebuild_auth / resol, **auto-mined from
the fix commit**) are never on a call path. Honestly downgraded — it now ranks
*below* urllib3, instead of being a loud, undifferentiated MEDIUM.

urllib3 — ne directly, but requests depends on it →

transitively reachable closure (package-level, no symbol data).

jinja2@2.10 — a real CVSS 9.8 RCE (C), declared but

ne → discounted to LOW and emitted as not_affected in VEX.

reqests — not a CVE at all: a typosquat of requests.

--explain prints the e DAG behind each number ( source, OS
match, the reachability call path, threat intel).

Cross-package reachability — the same finding, sharpened by e

First-party analysis can prove you call requests.get, but not whether get
internally reaches the ** function. Point --deps-path at the
dependency sources (a venv's site-packages, a tree — auto-detected for
a project .venv) and the engine descends into the library's own call graph:

The upgrade is backed by a pro path, printed under --explain:

The reverse also holds: if the dependency's call graph proves the public API you
use can never reach the function, the finding becomes
pro and is emitted as not_affected in VEX — a defensible suppression,
not a guess.

---

Architecture

Pipeline:

Out of band: habir mine parses fixing-commit patches into a CVE → affected-
function map (AST line-spans when source is a, git hunk headers otherwise),
which the call graph then targets.

---

The risk model (fully transparent)

exposure is where reachability pays off. A call-graph path to the
function — first-party (REACH:SYM) or pro dependency internals
(REACH:DEEP) — scores 1.0. A package used but whose function the
first-party graph ne is 0.6 (indirect). When the dependency's own
graph *proves* the sink is unreachable (pro) it drops to 0.3, on par
with a package that is ne.

Guardrails: a KEV (actively exploited) finding ne below MEDIUM,
so a real-world threat is surfaced even on an unreachable package. The
pre-confidence raw score is always reported — nothing is hidden by the
discount. Same inputs ⇒ identical output, byte for byte ( by tests).

---

Outputs

| Format | Use |
|---|---|
| terminal | humans; --explain adds the e DAG |
| json | the machine source of truth (findings + e + manifest) |
| sarif | GitHub Code Scanning / CI; risk, EPSS, KE ride in properties |
| vex | Open; reachability drives affected / not_affected |

---

Determinism & reproducibility

Every scan records a DB snapshot content-hash plus SHA-256 of each input
manifest, and prints a reproduce command. A finding is replayable to the exact
database state it was produced against — the property that makes this usable for
audit and forensics, not just CI gating.

---

Honesty about the bundled data

The shipped database is a small, labeled seed so the tool runs offline out
of the box:

OS (habir/data/seed/osv/) — 5 *real* ad with accurate

ranges and C.

EPSS (epss.csv) — clearly marked illustrati .

KEV (kev.json) — intentionally empty. None of the demo CVEs are in

the real CISA KE, and the tool will not falsely stamp a CVE as
actively exploited. The KE logic is proven in
tests/test_risk.py with synthetic fixtures.

habir db sync is the seam where a production mirror (full OS, live
FIRST.org EPSS, the real CISA KEV feed) replaces the seed. The engine is
identical; only the snapshot changes.

---

Roadmap

This 0.1.0-beta already ships the analysis layers usually gated behind
commercial tiers. The labels below describe *capabilities*, not package .

Shipped

Lockfile-first resolution · OS · EPSS/KEV · deterministic risk.

Patch-diff symbol mining → automated CVE → affected-function DB (habir mine).

Function-level (first-party) call-graph reachability.

Cross-package reachability into dependency internals (--deps-path → REACH:DEEP

/ pro).

Planned

Live db sync from OS.org EPSS / CISA KE; lockfile hash .

Dependency-confusion + beha install-script analysis (Socket-class).

Type-aware data-flow taint (precise source→sink) replacing the name-based graph; Rust core.

Static × dynamic reachability (sys.monitoring / eBPF runtime confirmation).

The data moat

Precise SCA is bottlenecked by the CVE → affected-symbol mapping, which Snyk and
Endor Labs curate by hand. habir mine derives it automatically and
deterministically from the fixing commit's diff — AST line-spans map the changed
lines to the innermost enclosing def/class (qualified Class.method), with a
git hunk-header fallback when no source checkout is a. In the demo, the
requests ad ships with no hand-authored symbols; mining recovers
rebuild_auth / resol from the patch, and the call graph then shows
they are ne — the full automated path from "raw CVE" to "honest ."

---

Tests

Every input path is hardened: malformed lock files, corrupt ad, broken
patches and bad DB rows are reported as warnings, ne. The analyzer is
itself safe — it parses untrusted manifests and source with tomllib / json /
ast.parse only (no eval, exec, pickle, or yaml.load), so the tool that
audits your supply chain ne part of its attack surface.

Design principles

Determinism o · Transparency o · Local-first.
Every finding must explain itself, and the tool that audits your supply chain
adds nothing to it.

项目信息

开发语言：Python

Star 数：9

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Deterministic, reachability-aware software composition analysis (SCA) engine — lockfile-first resolution, function- & cross-package reachability, patch-diff symbol mining, EPSS/KEV, SARIF + OpenVEX. Zero runtime dependencies.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。