Investigate GitHub secret scanning alerts to trace provenance, gather context,
assess risk, and produce a structured report for security professionals.
Handles one or more alerts in a single investigation using only open-source tools.
Investigate GitHub secret scanning alerts to trace provenance, gather context,
assess risk, and produce a structured report for security professionals.
Handles one or more alerts in a single investigation using only open-source tools.
The coordinator reads all artifacts ONCE during synthesis phase.
Phase Overview
Phase 0: Environment Setup
Verify required tools (gh, git) and offer to install optional tools (trufflehog, gitleaks, ggshield).
READ: references/phases/phase-0-setup.md for tool check details and installation commands.
Phase 0.5: Permission Pre-Approval
Present all read-only commands upfront for batch approval to minimize interruptions.
READ: references/phases/phase-0.5-permissions.md for permission request format.
Phase 1: Initial Triage and Mode Selection
Fetch basic alert details and require user to select PASSIVE or ACTIVE mode.
READ: references/phases/phase-1-triage.md for mode selection prompts.
Phases 2-6: Investigation
Deep investigation including alert acquisition, multi-tool scanning, provenance tracing, and secret-specific analysis.
READ: references/phases/phases-2-6-investigation.md for detailed procedures.
Phase 7: Risk Assessment
Evaluate risk factors and produce overall rating (CRITICAL/HIGH/MEDIUM/LOW).
READ: references/phases/phase-7-risk.md for risk criteria and assessment format.
Phase 8: Report Generation and Actions
8.1 Generate Report
After investigation completes, generate comprehensive report.
READ: references/report-template.md for the full report structure.
8.2 Output Options Menu
===============================================================
INVESTIGATION COMPLETE
===============================================================
Investigation Mode: {ACTIVE/PASSIVE}
Alerts Analyzed: {count}
Risk Rating: {CRITICAL/HIGH/MEDIUM/LOW}
OUTPUT OPTIONS:
1. Display report here
2. Save report to local file
3. Display and save
ADDITIONAL ACTIONS AVAILABLE:
4. Resolve alert(s) on GitHub
5. Generate SARIF output for security dashboard
6. Generate history cleanup commands
7. Generate prevention recommendations (pre-commit hooks, CI/CD)
8. Check for public leaks (requires ggshield)
9. Create GitHub issue with findings
10. Export timeline as CSV
11. Generate permanent permissions (settings.json)
Which options would you like? (comma-separated, e.g., "1,4,6"):
Action Reference Files
Each action has detailed implementation guidance:
Option
Action
Reference
4
Resolve Alert
references/actions/resolve-alert.md
5
SARIF Output
references/actions/sarif-output.md
6
History Cleanup
references/actions/history-cleanup.md
7
Prevention
references/actions/prevention.md
8
Public Leak Check
Uses ggshield (inline)
9
GitHub Issue
references/actions/github-issue.md
10
Timeline CSV
references/actions/timeline-csv.md
11
Permissions
references/actions/permissions.md
READ: references/actions/rotation-guides.md for credential rotation instructions.
Batch Processing
When multiple alerts are provided:
Run Phase 0 (tool check) once
Ask for mode selection once (applies to all unless user specifies otherwise)
Process each alert through Phases 2-7
Generate combined report with:
Shared executive summary noting patterns
Individual alert sections
Combined timeline showing relationships
Aggregate risk assessment
For Phase 8 actions, offer batch operations with explicit per-alert confirmation
Error Handling
Error
Handling
Alert not found
Report error, continue with other alerts if batch
Insufficient permissions
Document limitation, use available data, note in report
Clone fails
Fall back to API-based history, note limitation
Tool not available
Skip that analysis, note in report what was missed
Rate limiting
Wait and retry with backoff, or document incomplete analysis
Active verification refused
Fall back to passive analysis for that secret
Tool Requirements Summary
Tool
Required
Purpose
License
Install
gh
Yes
GitHub API access
MIT
brew install gh
git
Yes
History analysis
GPL-2.0
Pre-installed
trufflehog
No
Verification, analysis
Apache-2.0
brew install trufflehog
gitleaks
No
Cross-validation, SARIF
MIT
brew install gitleaks
ggshield
No
Public leak check
MIT
pip install ggshield
python3
No
Entropy calculation
PSF
Pre-installed
All optional tools are free and open-source.
Example Invocations
# Single alert by URL
"Investigate https://github.com/org/repo/security/secret-scanning/19"
# Single alert by components
"Investigate secret scanning alert #19 in org/repo"
# Multiple alerts
"Investigate secret scanning alerts #19, #20, #21 in org/repo"
# All open alerts in repo
"Investigate all open secret scanning alerts in org/repo"
# Organization-wide
"Investigate all critical secret scanning alerts in the org organization"