Hardik Zinzuvadiya
2482cc9fd0
Squashed rework of hackingtool from a tool launcher into an AI-guided operator
console for authorized security testing. 93 commits collapsed into this one;
the pre-rework tree is tagged v2.0.0.
CATALOG & ENGINE
- Data-driven YAML catalog (21 categories, 215 live tools + 59 archived) with a
registry/overlay loader and a fixed 66-tag taxonomy (63 in use). Adding a tool
is one YAML entry, not edits across the codebase.
- Engine honesty: real exit codes, truthful install success/failure, reuse-first
skip, EOF-safe prompts, command audit logging.
- Safe installs: sha256-required safe-fetch (killed `curl | bash` in feroxbuster,
Caido and Sliver), list-form subprocess only, no forced sudo.
AI LAYER (bring-your-own-key or local model; degrades offline, never fabricates)
- AI1 intent -> tools; AI2 tool+goal -> command, curated-first with a grounded
fallback; AI3 findings summary and engagement report; AI4 per-finding impact
and remediation. Prompt-injection hardened per OWASP LLM01.
- /goal plans an objective and runs it one step at a time, showing every command
before it runs, with a plan.json + run.log audit trail.
/find TOOL DISCOVERY (this branch's headline feature)
- Suggests real GitHub projects when the catalog has no tool for a need.
Deterministic: zero model calls, structured API fields only, suggest-only —
it never clones, installs or runs anything.
- A charter filter refuses destructive/DoS/jamming/mass-targeting/evasion asks
before any network I/O, while a defensive-intent guard keeps blue-team and
DFIR phrasing ("detect a SYN flood in a pcap") from being false-refused.
- Query rewriting proved to be the dominant quality lever (the first design
measured 29% precision with no results on 5 of 8 needs): a curated 41-row
intent table maps plain English to canonical jargon plus a GitHub topic, and
a two-arm search unions topic coverage with jargon precision.
- Explainable additive ranking: log-flattened stars, license/age/language,
trusted-author bonus derived from owners we already ship, docs-repo demotion
by name, staleness as a soft demotion rather than a filter (a hard cutoff
would delete THC-Hydan and John the Ripper), and a relevance term weighting
curated topics above free-text description.
- Optional no-scope GitHub token purely as a rate-limit lever (10 -> 30 req/min);
it reaches only an Authorization header, never a cache key, log or output.
- `[a]` saves a pick to ~/.hackingtool/found.yaml as a structurally inert entry,
and the loader strips executable keys from user catalogs at read time so a
hand-edited file cannot become a runnable command.
CONSOLE & PACKAGING
- REPL with a / command palette, @ tool mentions, tag filters, history and
completion; background tmux panes; settings and first-run scaffolding.
- src-layout package with catalog and pipelines as package data, console entry
point, Docker image, signed releases with SBOM and build provenance.
- Health docs (SECURITY, CONTRIBUTING, CHANGELOG, CODE_OF_CONDUCT), a CI gate
(ruff + pytest + catalog/taxonomy conformance) and a pre-push hook.
- README rewritten with a section index, the tool catalog split into
docs/TOOLS.md and a step-by-step docs/HOW-TO-USE.md.
278 tests passing; scripts/check.sh green.
3.5 KiB
Security Policy
hackingtool is a launcher and guidance layer for authorized security testing.
This policy covers vulnerabilities in hackingtool itself — not in the third-party
tools it can install or run.
Supported versions
Only the latest released version receives security fixes. Please reproduce on the
current master / latest PyPI release before reporting.
| Version | Supported |
|---|---|
| latest release | ✅ |
| older | ❌ |
Reporting a vulnerability
Please do not open a public issue for a security bug.
Report privately through GitHub's private advisory flow:
➡ https://github.com/Z4nzu/hackingtool/security/advisories/new
Include:
- what the vulnerability is and where (file / function / command),
- steps to reproduce (a minimal PoC is ideal),
- the impact you think it has, and
- the version / commit you tested.
We aim to acknowledge within 5 business days and to ship a fix or a mitigation plan within 30 days for a confirmed, in-scope report. We'll credit you in the release notes unless you ask us not to.
What's in scope
Vulnerabilities in hackingtool's own code, for example:
- Command / argument injection in the launcher, orchestrator, or any place user or catalog input reaches a subprocess.
- Unsafe downloads — a fetch that isn't pinned + SHA-256 verified, or a path that
reintroduces
curl | bash. - Prompt injection in the AI layer (recommend / command / summary / report) that makes the model fabricate, exfiltrate, or drive an action outside its guardrails — see OWASP LLM01: Prompt Injection.
- Privilege / path issues — unexpected
sudo, writing outside the user's~/.hackingtool/workspace, world-writable files, symlink traversal. - Catalog integrity — a catalog/overlay entry that ships an unsafe command, an unpinned installer, or a fabricated invocation.
What's out of scope
- The third-party tools themselves. A bug in nmap, sqlmap, hashcat, etc. belongs to that project — report it upstream. hackingtool only launches them.
- "This software can be used to attack things." That is the nature of an ethical-hacking toolkit. Misuse by an operator against systems they are not authorized to test is not a vulnerability in hackingtool. See Authorized use.
- Findings that require an already-compromised host or physical access.
- Reports from automated scanners with no demonstrated impact.
Verifying a release
Release artifacts are signed with SLSA build provenance and ship a CycloneDX SBOM, both attested via Sigstore. Verify what you install:
# PyPI wheel/sdist and the GitHub release .deb carry build-provenance attestations
gh attestation verify <artifact> --repo Z4nzu/hackingtool
# The SBOM (attached to each GitHub release as hackingtool.cdx.json) is attested too
gh attestation verify dist/hackingtool-*.whl --repo Z4nzu/hackingtool --predicate-type https://cyclonedx.org/bom
PyPI uploads additionally carry PEP 740 digital attestations, generated automatically via Trusted Publishing.
Authorized use
hackingtool is for security testing you are legally authorized to perform — your own systems, an engagement with written scope, a lab, or a CTF. Using it against systems you do not own or have explicit permission to test is illegal and is not a use we support. Every feature assumes authorized-targets-only, no blanket root, and no fabricated results.