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.
2.4 KiB
Contributor Code of Conduct
Our pledge
We as members, contributors, and maintainers pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
Our standards
Examples of behavior that contributes to a positive environment:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility, apologizing to those affected by our mistakes, and learning from the experience
- Focusing on what is best for the overall community
Examples of unacceptable behavior:
- Sexualized language or imagery, and sexual attention or advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information without explicit permission
- Soliciting or sharing help with unauthorized, illegal hacking. This is a toolkit for authorized security testing; using the community to coordinate attacks on systems you don't own or aren't permitted to test is not tolerated.
- Other conduct which could reasonably be considered inappropriate in a professional setting
Enforcement responsibilities
Maintainers are responsible for clarifying and enforcing these standards and will take appropriate, fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
Reporting
Report abusive, harassing, or otherwise unacceptable behavior privately to the maintainers through GitHub's private report flow: https://github.com/Z4nzu/hackingtool/security/advisories/new. All complaints will be reviewed and investigated promptly and fairly. Maintainers must respect the privacy and security of the reporter of any incident.
Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.