Perform a supply chain vulnerability analysis across ADT ecosystem repos. Verifies commit signing, PR traceability, CI integrity, and dependency provenance within a time frame. Generates a standalone HTML dashboard report and PDF.
Instrucciones de origen · Vista previa de solo lectura
name
td-supply-chain-audit
description
Perform a supply chain vulnerability analysis across ADT ecosystem repos. Verifies commit signing, PR traceability, CI integrity, and dependency provenance within a time frame. Generates a standalone HTML dashboard report and PDF.
The compromise-date is the date the package is suspected to have been compromised.
Prerequisites
gh CLI installed and authenticated (gh auth status must succeed)
python3 available (3.10+)
Network access to GitHub API, PyPI/npm registries, and GitHub releases (for Scorecard CLI auto-bootstrap)
GitHub token available to gh / GH_TOKEN (Scorecard CLI uses it for API rate limits)
playwright Python package with Chromium (for PDF export): pip install playwright && playwright install chromium
Do not ask the user to install Scorecard manually. collect.py auto-downloads the pinned scorecard binary into .supply-chain-audit/bin/ when missing ( — amd64/arm64), then scores every target repo that has no published OpenSSF API result. The CLI fallback runs the full Scorecard suite (OSV dependency scan) — that check can hang for 15+ minutes on larger repos, and dependency CVEs are already covered by the audit's separate OSV.dev inventory pass.
macOS, Linux, and Windows
except
Vulnerabilities
Instructions
Step 1: Validate inputs
Parse $ARGUMENTS to extract:
start_date and end_date (required, ISO format YYYY-MM-DD)
Optionally: package_name and compromise_date (for Phase 2)
If arguments are missing or malformed, ask the user to provide them in the correct format and stop.
Verify prerequisites:
gh auth status
python3 --version
If either fails, inform the user and stop.
Step 2: Run data collection
Execute the collection script from the skill's scripts directory:
Fetch commits, PRs, check suites, and dependency diffs for all target repos
Fetch all individual commits and review timelines within each merged PR
Fetch branch protection rules and rulesets for each repo
Detect OpenSSF Scorecard workflow presence and fetch published scores from the Scorecard API
Auto-bootstrap the Scorecard CLI if needed, then score every repo with no API result (all target environments/repos; skip only with --skip-scorecard-cli)
When commit/PR data is cached but Scorecard scores are still missing, automatically re-run Scorecard collection for those repos
Store results as JSON in the cache directory
Write a manifest.json for reproducibility
The script is idempotent: if cache files already exist for the same time frame, they are reused without re-fetching (Scorecard is refreshed automatically when scores are still unavailable).
Monitor progress output. The script prints per-repo status. If rate-limited, it will back off automatically.
Output: package_focus.json in the cache directory.
Step 5: Write security recommendations
After analysis completes, you (the agent) must read the findings and write a prioritized top-10 list of actionable security recommendations specific to what was found.
Read the findings summary: .supply-chain-audit/cache/<hash>/findings_summary.json (compact aggregate view — categories, risk counts, per-repo breakdown, top findings per category)
If you need more detail on specific findings, read the full: .supply-chain-audit/cache/<hash>/findings.json
Read the protection rules: .supply-chain-audit/cache/<hash>/protection/*.json
Read the renovate configs: .supply-chain-audit/cache/<hash>/renovate/*.json
Read the Scorecard data: .supply-chain-audit/cache/<hash>/scorecard/*.json
Reason about the most impactful actions the team should take based on:
Severity and count of findings by category
Patterns across repos (e.g., many repos missing the same protection)
Quick wins vs. systemic improvements
What would prevent the worst findings from recurring
Write .supply-chain-audit/cache/<hash>/recommendations.json as a JSON array of objects:
[{"title":"Short actionable title","detail":"HTML-safe explanation with context, affected repos, and concrete steps."}]
Guidelines for writing recommendations:
Be specific to what was actually found (reference repo names, counts, categories)
Order by impact: what would eliminate the most critical/high findings first
Don't be generic — tailor every recommendation to this audit's actual data
Link findings to their root cause (e.g., "bot-only approvals exist because branch protection doesn't require human review")
Process/behavioral changes — team policies, review norms, merge hygiene (e.g., "adopt a policy that bot-only approvals are never sufficient for human-authored code", "require a second human reviewer for changes to CI or dependency files")
Don't just tell them what to configure — tell them what habits to adopt and what behaviors to stop tolerating
Concrete examples: "Stop merging PRs with only bot approval", "Rotate a security champion weekly to review this report", "Treat post-approval commits as a blocking concern in code review culture"
Provide the paths to the HTML and PDF report files
Highlight the top 3 recommendations with brief rationale
If Phase 2 was run, summarize which repos pulled in the suspect package and when
If critical findings are detected (bypassed CI, post-merge pushes, suspicious dep timing), highlight these prominently and recommend immediate investigation.
Cache Behavior
Cache location: .supply-chain-audit/cache/
Cache key: first 16 hex chars of SHA-256(start_date + end_date + sorted_repo_list)
Re-running with identical parameters produces identical output
To force a fresh collection, delete the cache directory or pass --force to collect.py
Git history is effectively immutable for merged PRs; cached data reflects the state at collection time
