165 lines
6.0 KiB
Markdown
165 lines
6.0 KiB
Markdown
---
|
|
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>
|