Hypergumbo's safety claims are checked by running hypergumbo against its own source: hypergumbo verify-claims . --claims docs/hypergumbo.claims.yaml, gated in CI by scripts/check-self-claims.

Read the claims below as CLAIMS UNDER TEST, not as assurances. They state what each entry-point category is intended to do. What the analysis actually reports is:

The inconclusive verdicts are not near-misses. This repository contains code in languages with no taint catalogue, so the analysis declines to confirm rather than reporting silence as safety. A confirmed verdict requires every code-bearing language present to be analysable.

A violated verdict from this tool is trustworthy; a confirmed one means “found nothing, having looked at what it could see”. What it can see is bounded by the known limitations at the end of this section.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs

add-extras-no-host-fs — INCONCLUSIVE (the analysis could not see enough to confirm) — add-extras / remove-extras dispatch to install_* subcommands but do not perform writes outside the wrapper functions themselves.

add-extras-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — add-extras / remove-extras do not transitively reach dev-zone code paths.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs
• install_artifact

build-grammars-no-host-fs — INCONCLUSIVE (the analysis could not see enough to confirm) — build-grammars writes ONLY through tmp_artifact wrappers — the build dir scaffolding goes through tmp_artifact_write, and the install effect is via the pip subprocess.

build-grammars-no-install-artifact — INCONCLUSIVE (the analysis could not see enough to confirm) — build-grammars does not directly copy install artifacts; pip handles the install side via subprocess.

build-grammars-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — build-grammars does not transitively reach dev-zone code paths.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs
• install_artifact

install-embeddings-no-host-fs — INCONCLUSIVE (the analysis could not see enough to confirm) — install-embeddings does not write directly to arbitrary filesystem paths. The pip subprocess writes to site-packages on its own; hypergumbo's code does not write outside its wrappers.

install-embeddings-no-install-artifact — INCONCLUSIVE (the analysis could not see enough to confirm) — install-embeddings does not copy install artifacts to ~/.local/bin or similar (no install_artifact wrapper calls).

install-embeddings-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — install-embeddings does not transitively reach dev-zone code paths.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs

install-gitleaks-no-host-fs — INCONCLUSIVE (the analysis could not see enough to confirm) — install-gitleaks writes ONLY through install_artifact / tmp_artifact wrappers — never directly to arbitrary filesystem paths.

install-gitleaks-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — install-gitleaks does not transitively reach dev-zone code paths.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs
• install_artifact

install-rust-analyzer-no-host-fs — INCONCLUSIVE (the analysis could not see enough to confirm) — install-rust-analyzer delegates entirely to the rustup subprocess — hypergumbo's code does not write to disk directly.

install-rust-analyzer-no-install-artifact — INCONCLUSIVE (the analysis could not see enough to confirm) — install-rust-analyzer does not call any install_artifact wrappers (rustup handles install side-effects).

install-rust-analyzer-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — install-rust-analyzer does not transitively reach dev-zone code paths.

Prohibited zones (claim: zero unsanitized reach):

• dev_zone
• host_fs
• install_artifact
• network
• subprocess

runtime-cli-no-host-fs — ⚠ CURRENTLY VIOLATED — Runtime CLI subcommands (cmd_sketch, cmd_run, cmd_slice, cmd_search, cmd_routes, cmd_explain, cmd_symbols, cmd_compact, cmd_io_boundaries, cmd_verify_claims, cmd_catalog, cmd_test_coverage, cmd_dead_code_maybe, cmd_config, cmd_cache_status, cmd_cache_clear) do not write to arbitrary filesystem paths. All writes go through the safety_zones wrappers (cache_write / user_out_write / tmp_artifact_write) in their respective peer zones.

runtime-cli-no-network — INCONCLUSIVE (the analysis could not see enough to confirm) — Runtime CLI subcommands do not initiate network sends. Embeddings downloads happen only via the install-embeddings extras subcommand and downstream library calls — never from the analyze-my-code path.

runtime-cli-no-subprocess — ⚠ CURRENTLY VIOLATED — Runtime CLI subcommands do not shell out. All subprocess invocations (curl, git, pip, rustup, gitleaks) happen only via extras / build-time subcommands.

runtime-cli-no-install-artifact — INCONCLUSIVE (the analysis could not see enough to confirm) — Runtime CLI subcommands do not install software (no writes via the install_artifact wrappers).

runtime-cli-no-dev-zone — INCONCLUSIVE (the analysis could not see enough to confirm) — Runtime CLI subcommands do not transitively reach dev-zone code paths (tracker sync, agent supervisor, repository mutation). Hypergumbo's analyze-my-code path is separated from its development tooling by package boundaries; this claim makes the separation machine-verifiable.

Hypergumbo's analysis is layered to keep the audit honest without overcommitting the tool to third-party-library coverage:

1. Built-in stdlib catalogs (packages/hypergumbo-core/src/hypergumbo_core/io_primitives/). Hypergumbo-the-tool's responsibility — stdlib IO primitives per language. Shipped to PyPI users.

2. Project-local catalog mechanism — the --taint-sources / --taint-sinks / --taint-sanitizers CLI flags and the extra_catalogs: key in claims YAML let any user declare per-project rules. This is the customization point.

3. Hypergumbo's own project-local catalog (docs/hypergumbo-self-catalog/). One specific use of layer 2 for this repo's self-audit. Not shipped to PyPI users — they don't inherit these declarations. The same mechanism is available to them for their own dependencies.

We do NOT recursively audit third-party dependency internals (pyyaml, tree-sitter, huggingface_hub, etc.). Trust your pinned dependency versions the same way you trust any pip install.

Hypergumbo's structural taint analysis matches sinks by callee name, not by argument value. Two open(path, "w") call sites are indistinguishable even when one writes to a cache directory and the other to a user-supplied path. To verify path-bounded claims, hypergumbo's own source code routes every write through a named wrapper in hypergumbo_core.safety_zones: cache_write / user_out_write / tmp_artifact_write / install_artifact_copy / etc. Each wrapper has a distinct callee name, so the project-local catalog can declare each one in its own safety zone.

This pattern works in any language hypergumbo supports. Go: func WriteCache(path, data). Rust: fn write_cache(...). Java: class SafeIO { public static void writeCache(...) }. The call-graph BFS is language-agnostic; only the discipline is per-project. If you want path-bounded claims for your own code, adopt the wrapper-function pattern and declare your wrappers in your project-local catalog.

Re-run the audit locally:

hypergumbo verify-claims --claims docs/hypergumbo.claims.yaml .

Each claim verifies that no unsanitized data from the source entry-point category reaches the prohibited safety zone. A regression that adds a network call to a runtime CLI handler (or routes a write outside the safety_zones wrappers) fails the gate.

Short-name sink matching is necessarily over-approximate at receivers the DDG cannot resolve — call-RHS bindings (x = requests.Session(); x.get(...)), parameter receivers, and closure captures. At those sites verify-claims may report findings on common method names (.get / .run / .replace / .write) that reach generic primitives the wrappers don't cover. Treat these as documented overapproximation rather than genuine safety regressions.

This paragraph used to end “the load-bearing claims (dev-zone unreachability from runtime CLI, install zones not reached from runtime CLI) verify cleanly”. They do not — both are inconclusive, not confirmed, because this repository contains code the taint analysis has no catalogue for.

Two further limitations bound EVERY confirmed verdict this tool emits, here or in a user's repository. pathlib.Path method calls are invisible to the I/O catalogue — a receiver-typing gap, so the most common way Python writes a file registers as no I/O boundary at all. And a language that emits even ONE call edge passes the coverage check while the rest of its call structure may be unanalysable: Kotlin emits one and misses roughly 95% of its catalogued sinks.

The surface above is narrower than it was: the post-DDG IR refinement pass (hypergumbo_core.taint_refine) rewrites python:external:0-0:NAME:unresolved dsts to a module-resolved form (e.g., python:os.environ:0-0:NAME:unresolved) when the data-dependence graph can prove what the receiver was bound to — typically receivers bound by file-scope imports or by local assignment to a module attribute. Sink-matching then runs against the resolved module, so the external-module exemption only applies to the residual unresolvable cases above.

Hypergumbo's own mutating callsites (shutil.rmtree for cache eviction and grammar-scaffold reset, Path.chmod for post-install +x, Path.unlink for uninstall) route through tightening wrappers in hypergumbo_core.safety_zones (cache_rmtree / tmp_artifact_rmtree / install_artifact_chmod / install_artifact_unlink) so the structural pass gets a distinct, zone-tagged callee per site. The wrapper discipline and the refinement pass are complementary: the refinement narrows the residual surface across the codebase generally; the wrappers eliminate it deterministically at hypergumbo's own mutation sites.

Only the latest minor version receives security updates. We recommend always running the latest release.

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them via email to:

hypergumbo-cybersecurity@iterabloom.com

• Description of the vulnerability
• Steps to reproduce
• Affected versions
• Potential impact
• Any suggested fixes (optional)

• Acknowledgment: Within 72 hours of your report
• Initial assessment: Within 1 week
• Resolution timeline: Depends on severity, but we aim for:
  • Critical: 7 days
  • High: 14 days
  • Medium: 30 days
  • Low: 60 days

We will keep you informed of our progress and coordinate disclosure timing with you.

The following are in scope for security reports:

• Remote code execution
• SQL injection, command injection, or similar injection attacks
• Authentication/authorization bypass
• Sensitive data exposure
• Denial of service (application-level)
• Supply chain attacks (malicious dependencies)

The following are generally out of scope:

• Vulnerabilities in dependencies (report these upstream, but let us know)
• Social engineering attacks
• Physical attacks
• Issues requiring unlikely user interaction

We support safe harbor for security researchers who:

• Make a good faith effort to avoid privacy violations, data destruction, or service disruption
• Only interact with accounts you own or with explicit permission
• Do not exploit vulnerabilities beyond what is necessary to demonstrate the issue
• Report vulnerabilities promptly and do not publicly disclose before we've had reasonable time to address them

We will not pursue legal action against researchers who follow these guidelines.

hypergumbo implements several security practices:

• Dependency scanning: pip-audit runs in CI to detect known vulnerabilities
• Security linting: bandit analyzes code for common security issues
• Secret scanning: trufflehog checks for accidentally committed secrets
• License auditing: Checks for problematic dependency licenses
• 100% test coverage: Required for all code changes

If you need to encrypt your report, please request our PGP key via the email above.