alexgreensh/repo-forensics / plugins/repo-forensics/skills/forensify
forensify
FlaggedCross-agent self-inspection of your AI-agent stack. Audits skills, MCP servers, hooks, plugins, commands, credentials, and memory files across Claude Code, Codex, OpenClaw, and NanoClaw. Produces a structured inventory and narrative briefing with cross-ecosystem risk analysis. Use when the user asks to audit their own setup, check what they have installed, review their agent stack security posture, or understand cross-tool interactions. Use when a user has accumulated skills/plugins/MCP servers over time and wants visibility into their attack surface. Use after installing new skills or plugins. Do NOT use for vetting external code before install (that is repo-forensics). Do NOT use for incident response during active attacks. Do NOT use for fixing or patching vulnerabilities (forensify is read-only).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.7 KB |
| config/ecosystem_roots.json | config | 16.5 KB |
| config/ecosystem_roots.md | markdown | 8.0 KB |
| config/seatbelt_subagent.sb | other | 1.1 KB |
| domains/commands.json | config | 457 B |
| domains/credentials.json | config | 590 B |
| domains/hooks.json | config | 482 B |
| domains/mcp.json | config | 374 B |
| domains/plugins.json | config | 366 B |
| domains/skills.json | config | 461 B |
| orchestrator/__init__.py | script | 88 B |
| orchestrator/analysis_dispatcher.py | script | 7.5 KB |
| orchestrator/contracts.py | script | 2.7 KB |
| orchestrator/scanner_driver.py | script | 5.9 KB |
| orchestrator/synthesis_presenter.py | script | 9.0 KB |
| prompts/domain_commands.txt | markdown | 1.6 KB |
| prompts/domain_credentials.txt | markdown | 2.0 KB |
| prompts/domain_hooks.txt | markdown | 1.6 KB |
| prompts/domain_mcp.txt | markdown | 1.5 KB |
| prompts/domain_plugins.txt | markdown | 1.3 KB |
| prompts/domain_skills.txt | markdown | 2.0 KB |
| prompts/synthesis.txt | markdown | 2.4 KB |
| references/architecture.md | markdown | 3.7 KB |
| scripts/build_inventory.py | script | 62.0 KB |
orchestrator/scanner_driver.py
View on GitHub"""
ScannerDriver — scan -> parse -> dedupe -> cap
First stage of the orchestrator split per architecture-strategist finding.
Takes a repo path, runs the repo-forensics scanner suite, parses JSON
output, deduplicates findings by finding_id, and caps the result set to
stay within token budgets.
This module bridges forensify's self-inspection use case with the existing
repo-forensics scanners. It does NOT re-implement any detection logic —
it calls the scanners as subprocesses and consumes their JSON output.
"""
from __future__ import annotations
import json
import os
import subprocess
import sys
from typing import Any, Dict, List, Optional
from .contracts import DomainJob
# Exit-code contract of the scanner suite. The codes are defined by
# aggregate_json.calculate_report_exit_code() —
# 0 = clean, 1 = HIGH/MEDIUM findings, 2 = CRITICAL findings,
# 99 = infrastructure error —
# and run_forensics.sh's final `case` block clamps anything else to 99.
# 0, 1 and 2 each write a complete aggregate report to stdout and are results;
# only 99 and anything unforeseen are failures.
SCANNER_REPORT_EXIT_CODES = (0, 1, 2)
def find_scanner_script() -> Optional[str]:
"""Locate run_forensics.sh relative to this file."""
here = os.path.dirname(os.path.abspath(__file__))
candidate = os.path.join(here, "..", "..", "repo-forensics", "scripts", "run_forensics.sh")
candidate = os.path.realpath(candidate)
if os.path.isfile(candidate):
return candidate
return None
def run_scanners(
target_path: str,
skill_scan: bool = False,
timeout: int = 300,
) -> Dict[str, Any]:
"""
Run repo-forensics scanners against a target path and return parsed
JSON output. Uses --format json so output is machine-parseable.
Returns the parsed aggregate JSON dict on success, or a dict with
_error key on failure.
"""
script = find_scanner_script()
if not script:
return {"_error": "run_forensics.sh not found"}
# Canonicalize and validate target path
target_path = os.path.realpath(target_path)
if not os.path.isdir(target_path):
return {"_error": "target_not_a_directory", "path": target_path}
cmd = ["bash", script, target_path, "--format", "json"]
if skill_scan:
cmd.insert(3, "--skill-scan")
try:
result = subprocess.run(
cmd,
capture_output=True,
text=True,
timeout=timeout,
cwd=os.path.dirname(script),
)
except subprocess.TimeoutExpired:
return {"_error": "scanner_timeout", "timeout": timeout}
except OSError as e:
return {"_error": "subprocess_failed", "detail": str(e)}
if result.returncode not in SCANNER_REPORT_EXIT_CODES:
return {
"_error": "scanner_exit_%d" % result.returncode,
"stderr": result.stderr[:500] if result.stderr else "",
}
try:
return json.loads(result.stdout)
except json.JSONDecodeError:
return {"_error": "invalid_json", "stdout_head": result.stdout[:200]}
def parse_findings(scanner_output: Dict[str, Any]) -> List[Dict[str, Any]]:
"""
Extract the flat list of findings from aggregate scanner output.
Handles both the top-level 'findings' key and per-scanner nested results.
"""
findings: List[Dict[str, Any]] = []
# Top-level findings array (aggregate_json.py format)
if "findings" in scanner_output:
findings.extend(scanner_output["findings"])
return findings
# Per-scanner results (fallback for non-aggregate output)
for key, val in scanner_output.items():
if isinstance(val, dict) and "findings" in val:
findings.extend(val["findings"])
elif isinstance(val, list):
findings.extend(val)
return findings
def dedupe_findings(
findings: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""
Deduplicate findings by finding_id (if present) or by (scanner, file, line)
composite key. Returns the deduplicated list preserving first-seen order.
"""
seen = set()
unique: List[Dict[str, Any]] = []
for f in findings:
fid = f.get("finding_id")
if not fid:
# Composite fallback key
fid = "%s:%s:%s" % (
f.get("scanner", "?"),
f.get("file", "?"),
f.get("line", "?"),
)
if fid in seen:
continue
seen.add(fid)
unique.append(f)
return unique
def cap_findings(
findings: List[Dict[str, Any]],
max_per_severity: int = 50,
max_total: int = 200,
) -> List[Dict[str, Any]]:
"""
Cap findings to stay within token budgets. Preserves severity ordering:
CRITICAL > HIGH > MEDIUM > LOW > INFO. Within each severity, preserves
first-seen order up to max_per_severity.
"""
severity_order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "INFO": 4}
# sorted() not .sort() — never mutate the caller's list
findings = sorted(findings, key=lambda f: severity_order.get(f.get("severity", "INFO"), 4))
by_sev: Dict[str, List[Dict[str, Any]]] = {}
for f in findings:
sev = f.get("severity", "INFO")
by_sev.setdefault(sev, []).append(f)
capped: List[Dict[str, Any]] = []
for sev in ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"]:
entries = by_sev.get(sev, [])
capped.extend(entries[:max_per_severity])
return capped[:max_total]
def filter_findings_for_domain(
findings: List[Dict[str, Any]],
domain_config: Dict[str, Any],
) -> List[Dict[str, Any]]:
"""
Filter findings to those relevant to a specific domain based on the
scanner names declared in the domain's JSON config.
"""
allowed_scanners = set(domain_config.get("scanners", []))
if not allowed_scanners:
return findings
return [
f for f in findings
if f.get("scanner", "") in allowed_scanners
]
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |