hack.proof

01 · What it does

The problem it solves

Tools like gitleaks, semgrep, osv-scanner and nuclei each cover one slice of security testing, and the real work is knowing which to run, with what flags, and how to read the output. This packages that as 18 markdown playbooks, each naming the exact tools, commands and false-positive traps for one area: secrets, dependencies, SAST, web and API testing, auth, containers, IaC, mobile, smart contracts and reporting. Two bash scripts handle the parts needing no judgement. Raw output lands in a timestamped directory, and a final skill compresses it into one ranked report.

02 · Setup

Before you start

• ✓git and bash
• ✓A full, non-shallow clone of the target repo — the secrets scan reads history
• ✓A coding agent (Claude Code, Cursor, Codex, Copilot, Cline, Windsurf), or just a terminal
• ✓Whichever of brew, go, pipx and cargo you have — bootstrap skips what is missing
• ✓Docker, only for MobSF and the gitleaks step in the bundled CI workflow

03 · Step by step

Getting it running

1. 01

   Clone into your project

   The universal path works with any agent: drop the repo in as .hack.proof and point your agent at a skill file. No plugin or special runtime needed.

   $git clone https://github.com/ca-who-codes/hack.proof.git .hack.proof
2. 02

   Establish scope and authorisation first

   Step 0 of the master playbook asks what the target is, what you are authorised to test, and which environment is safe to test actively. Staging usually tolerates aggressive testing; production usually does not.

3. 03

   Install the scanners

   bootstrap.sh detects your package managers and installs best-effort. It is idempotent, skips what it cannot install rather than aborting, and prints installed and skipped lists.

   $./scripts/bootstrap.sh
4. 04

   Point an agent at the master playbook

   full-security-audit chains the other skills in an order where each stage informs the next, and skips those that do not apply. Prompt: "Follow .hack.proof/skills/full-security-audit/SKILL.md against this repo and report findings."

5. 05

   Or run the scripted audit yourself

   A local path runs gitleaks, trufflehog, osv-scanner and semgrep, adding hadolint and trivy if a Dockerfile exists and checkov if it finds .tf files. A URL runs subfinder, httpx, testssl.sh and nuclei.

   $./scripts/full-audit.sh /path/to/your/project
6. 06

   Read the preflight toolcheck

   The script prints which tools are present and missing before running anything, so a thin toolbox does not quietly produce an empty report that looks clean.

7. 07

   Synthesise the ranked report

   Raw JSON is not a deliverable. Point an agent at the findings-report skill with the findings directory as input; it deduplicates across tools and reranks by exploitability, blast radius and reachability.

04 · What you get

Capabilities

05 · Before you rely on it

Limitations, honestly

Every tool has edges. These are the ones that will cost you time if nobody tells you first.

• !For authorised testing only. Scanning, fuzzing or exploiting systems you do not own or have written permission to test may be illegal regardless of intent.
• !bootstrap.sh detects apt-get but defines no apt install path, so on Linux without Homebrew most tools are skipped and must be installed by hand.
• !full-audit.sh only covers the scriptable half — web, API, auth, business-logic and smart-contract work need an agent or a human reading source.
• !The live-target branch is deliberately conservative, so a clean result there is not the same as a real pentest.
• !The secrets scan reads git history, so a shallow clone hides secrets that only exist in past commits.
• !Scan output routinely contains live credentials. The findings directory is gitignored — do not commit it, and rotate anything discovered.
• !In the bundled CI workflow only gitleaks is a hard gate; the semgrep step ends in || true.