salvacybersec/keyhunter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(07): create phase 7 import & CI/CD plans

Browse Source
This commit is contained in:
salvacybersec
2026-04-05 23:53:14 +03:00
parent 5c74c35a26
commit 779c5b3d6f
7 changed files with 1190 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
.planning/phases/07-import-cicd/07-06-PLAN.md Normal file
View File

@@ -0,0 +1,164 @@
---
phase: 07-import-cicd
plan: 06
type: execute
wave: 2
depends_on: ["07-04", "07-05"]
files_modified:
- docs/CI-CD.md
- README.md
autonomous: true
requirements: [CICD-01, CICD-02]
must_haves:
truths:
- "Users have a documented GitHub Actions workflow example that runs keyhunter and uploads SARIF"
- "Pre-commit hook setup is documented with install/uninstall commands"
- "README references the new CI/CD document"
artifacts:
- path: docs/CI-CD.md
provides: "CI/CD integration guide (GitHub Actions + pre-commit hook)"
contains: "github/codeql-action/upload-sarif"
- path: README.md
provides: "Top-level project README (updated to link CI/CD guide)"
key_links:
- from: README.md
to: docs/CI-CD.md
via: "markdown link"
pattern: "docs/CI-CD\\.md"
---
<objective>
Document the Phase 7 deliverables: import command usage, pre-commit hook lifecycle, and GitHub Actions workflow for SARIF upload.
Purpose: CICD-01 and CICD-02 require the integration to be discoverable by users. Code alone is not enough — a working workflow example and hook setup walkthrough are part of the requirement.
Output: docs/CI-CD.md, README section linking to it.
</objective>
<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/phases/07-import-cicd/07-CONTEXT.md
@README.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Write docs/CI-CD.md with GitHub Actions + pre-commit guide</name>
<files>docs/CI-CD.md</files>
<action>
Create docs/CI-CD.md with the following sections (markdown):
1. **Title & intro** — "KeyHunter CI/CD Integration" — one paragraph explaining scope: pre-commit hooks, GitHub Actions SARIF upload, importing external scanner output.
2. **Pre-commit Hook** section:
- Install: `keyhunter hook install` (explain what file is written, where).
- Override: `--force` flag backs up existing pre-commit as `pre-commit.bak.<timestamp>`.
- Bypass a single commit: `git commit --no-verify`.
- Uninstall: `keyhunter hook uninstall`.
- Note: only scans staged files via `git diff --cached --name-only --diff-filter=ACMR`.
3. **GitHub Actions (SARIF upload to Code Scanning)** section, with a full working workflow example saved as a fenced yaml block:
```yaml
name: KeyHunter
on:
push:
branches: [main]
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install KeyHunter
run: |
curl -sSL https://github.com/salvacybersec/keyhunter/releases/latest/download/keyhunter_linux_amd64.tar.gz | tar -xz
sudo mv keyhunter /usr/local/bin/
- name: Scan repository
run: keyhunter scan . --output sarif > keyhunter.sarif
continue-on-error: true
- name: Upload SARIF to GitHub Code Scanning
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: keyhunter.sarif
category: keyhunter
```
- Explain `continue-on-error: true` — scan exits 1 on findings; we want the SARIF upload step to still run. The findings show up in the Security tab.
- Explain the required `security-events: write` permission.
4. **Importing External Scanner Output** section:
- Running TruffleHog then importing:
```
trufflehog filesystem . --json > trufflehog.json
keyhunter import --format=trufflehog trufflehog.json
```
- Gitleaks JSON:
```
gitleaks detect -f json -r gitleaks.json
keyhunter import --format=gitleaks gitleaks.json
```
- Gitleaks CSV:
```
gitleaks detect -f csv -r gitleaks.csv
keyhunter import --format=gitleaks-csv gitleaks.csv
```
- Dedup guarantee: re-running the same import is idempotent.
5. **Exit Codes** section — table of 0/1/2 semantics for CI integration.
Keep the whole file under ~200 lines. No emojis.
</action>
<verify>
<automated>test -f docs/CI-CD.md && grep -q "upload-sarif" docs/CI-CD.md && grep -q "keyhunter hook install" docs/CI-CD.md && grep -q "keyhunter import --format=trufflehog" docs/CI-CD.md</automated>
</verify>
<done>
- docs/CI-CD.md exists with all 5 sections
- Required strings present (upload-sarif, hook install, import --format=trufflehog)
</done>
</task>
<task type="auto">
<name>Task 2: Update README.md with CI/CD integration link</name>
<files>README.md</files>
<action>
Read current README.md first.
Add (or update if a stub section exists) a "CI/CD Integration" H2 section that:
- Contains 2-4 sentences summarizing pre-commit hook + GitHub SARIF upload support.
- Links to `docs/CI-CD.md` for the full guide.
- Mentions `keyhunter import` for TruffleHog/Gitleaks consolidation.
Place the section after any existing "Installation" / "Usage" section and before "Development" or "License" sections. If those anchors don't exist, append near the end but before "License".
Do not rewrite unrelated parts of the README.
</action>
<verify>
<automated>grep -q "docs/CI-CD.md" README.md && grep -q "CI/CD" README.md</automated>
</verify>
<done>
- README.md references docs/CI-CD.md
- CI/CD Integration section exists
</done>
</task>
</tasks>
<verification>
grep -q "upload-sarif" docs/CI-CD.md && grep -q "docs/CI-CD.md" README.md
</verification>
<success_criteria>
CICD-01 and CICD-02 are discoverable end-to-end: a user landing on the README can find CI/CD guidance, follow it to docs/CI-CD.md, and copy a working GitHub Actions workflow + pre-commit setup.
</success_criteria>
<output>
After completion, create `.planning/phases/07-import-cicd/07-06-SUMMARY.md`.
</output>