attackmap 0.1.0__py3-none-any.whl

attackmap/recon_models.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+# Phase-1 shared recon/result model exports.
+# Keep ScanResult and recon signal models as the single source of truth via models.py.
+from .models import (
+    AuthHint,
+    DatabaseHint,
+    EdgeHint,
+    EntrypointHint,
+    ExternalCall,
+    FrameworkHint,
+    ProtocolHint,
+    Route,
+    ScanResult,
+    SecretHint,
+    ServiceHint,
+)
+
+__all__ = [
+    "Route",
+    "ExternalCall",
+    "DatabaseHint",
+    "AuthHint",
+    "ServiceHint",
+    "EdgeHint",
+    "EntrypointHint",
+    "ProtocolHint",
+    "FrameworkHint",
+    "SecretHint",
+    "ScanResult",
+]

attackmap/recon_to_analysis.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+from .analyzer import identify_attack_surfaces
+from .models import AttackPath, AttackSurface, AuthHint, Finding, ScanResult
+from .threat_model import generate_attack_paths, generate_findings
+
+
+@dataclass(frozen=True)
+class AnalysisOutputs:
+    attack_surfaces: list[AttackSurface]
+    findings: list[Finding]
+    attack_paths: list[AttackPath]
+
+
+NON_AUTH_HINT_PREFIXES: tuple[str, ...] = (
+    "service_name:",
+    "service_role:",
+    "entrypoint:",
+    "edge:",
+    "handler_type:",
+    "handler_visibility:",
+    "handler_visibility_basis:",
+    "controller:",
+    "service:",
+    "omeka_",
+    "laminas_",
+    "atproto_namespace:",
+    "atproto_namespace_ref:",
+    "atproto_xrpc_ref:",
+    "atproto_lexicon:",
+    "atproto_event_stream:",
+    "atproto_service_note:",
+    "atproto_service_edge:",
+    "atproto_repo:",
+)
+
+AUTH_SIGNAL_PATTERN = re.compile(
+    r"(auth|jwt|oauth|token|session|password|bearer|authorization|mfa|passport|login_required)",
+    re.IGNORECASE,
+)
+
+EXPLICIT_AUTH_HINT_PREFIXES: tuple[str, ...] = ("atproto_auth:",)
+
+
+def _is_likely_auth_signal(value: str) -> bool:
+    lowered = value.lower()
+    if lowered.startswith(EXPLICIT_AUTH_HINT_PREFIXES):
+        return True
+    if lowered.startswith(NON_AUTH_HINT_PREFIXES):
+        return False
+    return bool(AUTH_SIGNAL_PATTERN.search(lowered))
+
+
+def _auth_filtered_scan(scan: ScanResult) -> ScanResult:
+    """
+    Build a conservative auth-focused view of ScanResult.
+
+    Why:
+    `auth_hints` is temporarily overloaded with non-auth analyzer metadata
+    (service names, edges, protocol notes). For attack-surface and finding
+    generation, treat only likely auth signals as auth to avoid overconfidence.
+    """
+    migrated_non_auth_hints = {
+        (hint.hint, hint.file)
+        for hint in [
+            *scan.service_hints,
+            *scan.edge_hints,
+            *scan.entrypoint_hints,
+            *scan.protocol_hints,
+            *scan.framework_hints,
+        ]
+    }
+    filtered_auth_hints = [
+        hint
+        for hint in scan.auth_hints
+        if (hint.hint, hint.file) not in migrated_non_auth_hints and _is_likely_auth_signal(hint.hint)
+    ]
+    return scan.model_copy(update={"auth_hints": [AuthHint(hint=hint.hint, file=hint.file) for hint in filtered_auth_hints]})
+
+
+def to_attack_surface(scan: ScanResult) -> list[AttackSurface]:
+    """Translate recon signals into classified attack-surface entries."""
+    return identify_attack_surfaces(_auth_filtered_scan(scan))
+
+
+def to_findings(scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None) -> list[Finding]:
+    """Translate recon signals (and optional surfaces) into conservative findings."""
+    auth_filtered_scan = _auth_filtered_scan(scan)
+    if attack_surfaces is not None:
+        return generate_findings(auth_filtered_scan, attack_surfaces)
+    return generate_findings(auth_filtered_scan)
+
+
+def to_attack_paths(scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None) -> list[AttackPath]:
+    """
+    Translate recon signals into plausible, heuristic attack paths.
+
+    Keep full hints for path generation so temporary overloaded hints still
+    support chain-linking while migration is in progress.
+    """
+    return generate_attack_paths(scan, attack_surfaces=attack_surfaces)
+
+
+def translate_recon(scan: ScanResult) -> AnalysisOutputs:
+    """
+    Formal translation stage from ScanResult to higher-level analysis artifacts.
+
+    This remains deterministic and explainable by relying only on existing
+    signal-driven heuristics from analyzer/threat_model modules.
+    """
+    attack_surfaces = to_attack_surface(scan)
+    findings = to_findings(scan, attack_surfaces)
+    attack_paths = to_attack_paths(scan)
+    return AnalysisOutputs(
+        attack_surfaces=attack_surfaces,
+        findings=findings,
+        attack_paths=attack_paths,
+    )

attackmap/report.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .context_pack import build_review_context_pack
+from .models import AttackPath, AttackSurface, Finding, ScanResult
+from .review_json import build_defensive_review_json
+
+
+def _severity_rank(value: str) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(value, 3)
+
+
+def write_reports(
+    output_dir: str | Path,
+    scan: ScanResult,
+    architecture_md: str,
+    attack_surface_md: str,
+    defensive_review_md: str,
+    attack_surfaces: list[AttackSurface],
+    findings: list[Finding],
+    attack_paths: list[AttackPath],
+    analyzer_metadata: list[dict[str, object]] | None = None,
+) -> None:
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    (out / "architecture.md").write_text(architecture_md + "\n", encoding="utf-8")
+    (out / "attack-surface.md").write_text(attack_surface_md + "\n", encoding="utf-8")
+    (out / "defensive-review.md").write_text(defensive_review_md + "\n", encoding="utf-8")
+    defensive_review_json = build_defensive_review_json(scan, attack_surfaces, findings, attack_paths)
+    (out / "defensive-review.json").write_text(json.dumps(defensive_review_json, indent=2) + "\n", encoding="utf-8")
+    review_context_pack = build_review_context_pack(
+        defensive_review_json,
+        scan,
+        analyzer_metadata if analyzer_metadata is not None else [],
+    )
+    (out / "review-context-pack.json").write_text(json.dumps(review_context_pack, indent=2) + "\n", encoding="utf-8")
+
+    json_report = {
+        "scan": scan.model_dump(),
+        "architecture_summary": architecture_md,
+        "attack_surface_summary": attack_surface_md,
+        "defensive_review": defensive_review_md,
+        "defensive_review_json": defensive_review_json,
+        "review_context_pack": review_context_pack,
+        "attack_surfaces": [surface.model_dump() for surface in attack_surfaces],
+        "findings": [finding.model_dump() for finding in findings],
+        "attack_paths": [path.model_dump() for path in attack_paths],
+    }
+    (out / "attackmap-report.json").write_text(json.dumps(json_report, indent=2) + "\n", encoding="utf-8")
+
+
+def render_console_summary(scan: ScanResult, findings: list[Finding], attack_paths: list[AttackPath]) -> str:
+    ordered_findings = sorted(findings, key=lambda finding: (_severity_rank(finding.severity), finding.title))
+    lines = [
+        f"Scanned {scan.files_scanned} files",
+        f"Detected languages: {', '.join(scan.languages) if scan.languages else 'none'}",
+        f"Routes: {len(scan.routes)}",
+        f"External calls: {len(scan.external_calls)}",
+        f"Datastores: {len(scan.databases)}",
+        "",
+        "Findings:",
+    ]
+    for finding in ordered_findings:
+        lines.append(f"- [{finding.severity.upper()}] {finding.title}")
+
+    lines.append("")
+    lines.append("Attack paths:")
+    for path in attack_paths:
+        lines.append(f"- {path.name}: {path.impact}")
+
+    return "\n".join(lines)

attackmap/review_eval.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+def load_eval_fixture(path: str | Path) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def load_review_text(path: str | Path) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+
+def _extract_section(text: str, heading: str) -> str:
+    pattern = re.compile(rf"^\s*##\s+{re.escape(heading)}\s*$", re.MULTILINE)
+    match = pattern.search(text)
+    if match is None:
+        return ""
+    start = match.end()
+    next_heading = re.search(r"^\s*##\s+.+$", text[start:], re.MULTILINE)
+    end = start + next_heading.start() if next_heading else len(text)
+    return text[start:end].strip()
+
+
+def _extract_bullets(section_text: str) -> list[str]:
+    return [line.strip()[2:].strip() for line in section_text.splitlines() if line.strip().startswith("- ")]
+
+
+def _count_matches(text: str, pattern: str) -> int:
+    return len(re.findall(pattern, text, flags=re.IGNORECASE))
+
+
+def evaluate_review_text(review_text: str, fixture: dict[str, Any]) -> dict[str, Any]:
+    expectations = fixture.get("expectations", {})
+    checks: list[dict[str, Any]] = []
+
+    grounding = expectations.get("grounding", {})
+    citation_pattern = grounding.get("citation_pattern", r"(?:surface|finding|path):\d+")
+    citations = sorted(set(re.findall(citation_pattern, review_text, flags=re.IGNORECASE)))
+    allowed_ids = set(grounding.get("allowed_ids", []))
+    unknown_citations = sorted(citation for citation in citations if citation not in allowed_ids) if allowed_ids else []
+    min_citations = int(grounding.get("min_citations", 0))
+    grounding_pass = len(citations) >= min_citations and not unknown_citations
+    checks.append(
+        {
+            "name": "grounding",
+            "passed": grounding_pass,
+            "details": {
+                "citations_found": citations,
+                "unknown_citations": unknown_citations,
+                "min_citations_required": min_citations,
+            },
+        }
+    )
+
+    observed_inferred = expectations.get("observed_inferred", {})
+    observed_token = observed_inferred.get("observed_token", r"\bOBSERVED\b")
+    inferred_token = observed_inferred.get("inferred_token", r"\bINFERRED\b")
+    observed_count = _count_matches(review_text, observed_token)
+    inferred_count = _count_matches(review_text, inferred_token)
+    observed_required = int(observed_inferred.get("min_observed", 0))
+    inferred_required = int(observed_inferred.get("min_inferred", 0))
+    oi_pass = observed_count >= observed_required and inferred_count >= inferred_required
+    checks.append(
+        {
+            "name": "observed_vs_inferred_discipline",
+            "passed": oi_pass,
+            "details": {
+                "observed_count": observed_count,
+                "inferred_count": inferred_count,
+                "min_observed_required": observed_required,
+                "min_inferred_required": inferred_required,
+            },
+        }
+    )
+
+    strengths_expectation = expectations.get("strengths", {})
+    strengths_section = _extract_section(review_text, "Strengths")
+    strengths_items = _extract_bullets(strengths_section)
+    strengths_keywords = [keyword.lower() for keyword in strengths_expectation.get("required_keywords", [])]
+    strengths_text = strengths_section.lower()
+    missing_strengths_keywords = [keyword for keyword in strengths_keywords if keyword not in strengths_text]
+    min_strengths_items = int(strengths_expectation.get("min_items", 0))
+    strengths_pass = len(strengths_items) >= min_strengths_items and not missing_strengths_keywords
+    checks.append(
+        {
+            "name": "strengths_coverage",
+            "passed": strengths_pass,
+            "details": {
+                "item_count": len(strengths_items),
+                "min_items_required": min_strengths_items,
+                "missing_keywords": missing_strengths_keywords,
+            },
+        }
+    )
+
+    weakness_expectation = expectations.get("weaknesses_hotspots", {})
+    weakness_section = _extract_section(review_text, "Weaknesses / Risk Hotspots")
+    weakness_items = _extract_bullets(weakness_section)
+    min_weakness_items = int(weakness_expectation.get("min_items", 0))
+    weakness_terms = [term.lower() for term in weakness_expectation.get("required_terms", [])]
+    weakness_text = weakness_section.lower()
+    missing_weakness_terms = [term for term in weakness_terms if term not in weakness_text]
+    weakness_pass = len(weakness_items) >= min_weakness_items and not missing_weakness_terms
+    checks.append(
+        {
+            "name": "weakness_hotspot_quality",
+            "passed": weakness_pass,
+            "details": {
+                "item_count": len(weakness_items),
+                "min_items_required": min_weakness_items,
+                "missing_terms": missing_weakness_terms,
+            },
+        }
+    )
+
+    recommendation_expectation = expectations.get("recommendations", {})
+    recommendation_section = _extract_section(review_text, "Prioritized Recommendations")
+    recommendation_items = _extract_bullets(recommendation_section)
+    min_recommendation_items = int(recommendation_expectation.get("min_items", 0))
+    action_verbs = [verb.lower() for verb in recommendation_expectation.get("action_verbs", [])]
+    recommendation_text = recommendation_section.lower()
+    recommendation_verbs_present = [verb for verb in action_verbs if verb in recommendation_text]
+    recommendation_pass = len(recommendation_items) >= min_recommendation_items and bool(recommendation_verbs_present)
+    checks.append(
+        {
+            "name": "recommendation_usefulness",
+            "passed": recommendation_pass,
+            "details": {
+                "item_count": len(recommendation_items),
+                "min_items_required": min_recommendation_items,
+                "action_verbs_present": recommendation_verbs_present,
+            },
+        }
+    )
+
+    false_positive_expectation = expectations.get("false_positive_control", {})
+    banned_phrases = [phrase.lower() for phrase in false_positive_expectation.get("banned_phrases", [])]
+    lowered_review = review_text.lower()
+    found_banned = [phrase for phrase in banned_phrases if phrase in lowered_review]
+    required_cautions = [phrase.lower() for phrase in false_positive_expectation.get("required_cautions", [])]
+    missing_cautions = [phrase for phrase in required_cautions if phrase not in lowered_review]
+    false_positive_pass = not found_banned and not missing_cautions
+    checks.append(
+        {
+            "name": "false_positive_control",
+            "passed": false_positive_pass,
+            "details": {
+                "found_banned_phrases": found_banned,
+                "missing_required_cautions": missing_cautions,
+            },
+        }
+    )
+
+    passed_count = sum(1 for check in checks if check["passed"])
+    total_count = len(checks)
+    score = round((passed_count / total_count) * 100.0, 2) if total_count else 0.0
+    return {
+        "fixture_id": fixture.get("fixture_id", "unknown"),
+        "target": fixture.get("target", {}),
+        "summary": {
+            "score": score,
+            "passed_checks": passed_count,
+            "total_checks": total_count,
+            "status": "pass" if passed_count == total_count else "fail",
+        },
+        "checks": checks,
+    }
+
+
+def run_evaluation(fixture_path: str | Path, review_path: str | Path) -> dict[str, Any]:
+    fixture = load_eval_fixture(fixture_path)
+    review_text = load_review_text(review_path)
+    return evaluate_review_text(review_text, fixture)
+
+
+def _resolve_review_path_for_fixture(fixture_path: Path, fixture: dict[str, Any], reviews_dir: Path) -> Path:
+    configured = fixture.get("review_file")
+    if isinstance(configured, str) and configured.strip():
+        return (reviews_dir / configured).resolve()
+    return (reviews_dir / f"{fixture_path.stem}.md").resolve()
+
+
+def run_evaluation_suite(fixtures_dir: str | Path, reviews_dir: str | Path) -> dict[str, Any]:
+    fixture_dir_path = Path(fixtures_dir).resolve()
+    review_dir_path = Path(reviews_dir).resolve()
+    fixture_paths = sorted(fixture_dir_path.glob("*.json"))
+    cases: list[dict[str, Any]] = []
+
+    for fixture_path in fixture_paths:
+        fixture = load_eval_fixture(fixture_path)
+        review_path = _resolve_review_path_for_fixture(fixture_path, fixture, review_dir_path)
+        if not review_path.exists():
+            cases.append(
+                {
+                    "fixture_id": fixture.get("fixture_id", fixture_path.stem),
+                    "summary": {
+                        "score": 0.0,
+                        "passed_checks": 0,
+                        "total_checks": 1,
+                        "status": "fail",
+                    },
+                    "checks": [
+                        {
+                            "name": "review_file_presence",
+                            "passed": False,
+                            "details": {"missing_review_path": str(review_path)},
+                        }
+                    ],
+                }
+            )
+            continue
+        cases.append(run_evaluation(fixture_path, review_path))
+
+    passed = sum(1 for case in cases if case["summary"]["status"] == "pass")
+    total = len(cases)
+    avg_score = round(sum(case["summary"]["score"] for case in cases) / total, 2) if total else 0.0
+    return {
+        "suite": {
+            "fixtures_dir": str(fixture_dir_path),
+            "reviews_dir": str(review_dir_path),
+            "fixture_count": total,
+            "passed": passed,
+            "failed": total - passed,
+            "average_score": avg_score,
+            "status": "pass" if total > 0 and passed == total else "fail",
+        },
+        "cases": cases,
+    }
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description="Evaluate AttackMap defensive review output against a fixture spec.")
+    parser.add_argument("--fixture", help="Path to evaluation fixture JSON.")
+    parser.add_argument("--review", help="Path to review markdown output to evaluate.")
+    parser.add_argument("--fixtures-dir", help="Directory containing evaluation fixture JSON files.")
+    parser.add_argument("--reviews-dir", help="Directory containing review markdown outputs for suite mode.")
+    parser.add_argument("--json", action="store_true", help="Print full JSON result.")
+    args = parser.parse_args()
+
+    if args.fixtures_dir or args.reviews_dir:
+        if not (args.fixtures_dir and args.reviews_dir):
+            parser.error("--fixtures-dir and --reviews-dir must be used together.")
+        if args.fixture or args.review:
+            parser.error("Use either single mode (--fixture/--review) or suite mode (--fixtures-dir/--reviews-dir), not both.")
+        suite_result = run_evaluation_suite(args.fixtures_dir, args.reviews_dir)
+        if args.json:
+            print(json.dumps(suite_result, indent=2))
+        else:
+            summary = suite_result["suite"]
+            print(f"Suite fixtures: {summary['fixture_count']}")
+            print(f"Pass: {summary['passed']}, Fail: {summary['failed']}, Average score: {summary['average_score']}")
+            print(f"Status: {summary['status']}")
+            for case in suite_result["cases"]:
+                case_summary = case["summary"]
+                print(f"- {case['fixture_id']}: {case_summary['status']} ({case_summary['score']})")
+        return 0 if suite_result["suite"]["status"] == "pass" else 1
+
+    if not (args.fixture and args.review):
+        parser.error("Single mode requires --fixture and --review.")
+
+    result = run_evaluation(args.fixture, args.review)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        summary = result["summary"]
+        print(f"Fixture: {result['fixture_id']}")
+        print(f"Score: {summary['score']} ({summary['passed_checks']}/{summary['total_checks']} checks)")
+        print(f"Status: {summary['status']}")
+        for check in result["checks"]:
+            mark = "PASS" if check["passed"] else "FAIL"
+            print(f"- {mark}: {check['name']}")
+    return 0 if result["summary"]["status"] == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())