attackmap 0.6.4__py3-none-any.whl

attackmap/detections/webhook.yml

@@ -0,0 +1,45 @@
+# Webhook signature rules (#251, extends the #243 opportunity). A genuine
+# provider delivery always carries its signature header; a POST to the
+# webhook route without one is a forging attempt (or a misrouted client).
+# Access logs only carry a request header when you add it as a custom field;
+# the rule uses the W3C/IIS custom-field name `cs(<Header>)`. Map it to
+# whatever your log pipeline calls the field.
+
+templates:
+  webhook-signature-missing:
+    date: "2026-10-12"
+    title: "Webhook delivery without a signature header"
+    description: >-
+      POST requests to ${routes_text} that carry no ${provider_text}
+      signature header. AttackMap found ${state_text} on these routes
+      (rules ${rule_ids_text}), so a forged event would be processed. Also
+      alert on requests whose signature fails verification, on stale
+      timestamps and on replayed delivery ids from your application log.
+    logsource:
+      category: webserver
+    fields_required: "${fields}"
+    detection: "${detection}"
+    falsepositives:
+      - Provider connectivity checks that send no signature (some providers ping the endpoint when it is configured)
+      - A provider that signs with a header not listed here; add it to the rule
+    level: medium
+    test_events:
+      positive:
+        - cs-method: POST
+          cs-uri-stem: "${route_example}"
+          sc-status: 200
+      negative:
+        - "${signed_event}"
+        - cs-method: GET
+          cs-uri-stem: "${route_example}"
+          sc-status: 200
+
+data:
+  # Provider -> the header(s) that carry its signature.
+  headers:
+    github: [X-Hub-Signature-256, X-Hub-Signature]
+    stripe: [Stripe-Signature]
+    slack: [X-Slack-Signature]
+    shopify: [X-Shopify-Hmac-Sha256]
+    svix: [svix-signature, webhook-signature]
+    twilio: [X-Twilio-Signature]

attackmap/detections/workflow.yml

@@ -0,0 +1,121 @@
+# CI workflow rules (#251, part 2). A workflow that runs untrusted code with
+# secrets or a write token can't be watched from inside the job, but the
+# GitHub audit log shows every run and the cloud provider shows what the
+# run's OIDC token was used for.
+#
+# GitHub audit log field names follow the audit-log streaming schema
+# (`action`, `actor`, `repo`, and per-event keys such as `event` on
+# `workflows.created_workflow_run`). They are experimental here: confirm
+# them against a sample event from your stream before alerting.
+
+templates:
+  github-untrusted-trigger-run:
+    date: "2026-10-12"
+    title: "GitHub Actions run triggered by ${trigger_text}"
+    description: >-
+      A workflow run created by a ${trigger_text} event. AttackMap found
+      ${kind_label} in ${location} (rule ${rule_id}), so a run started from a
+      fork or by an outside actor executes attacker-controlled code with the
+      workflow's secrets and token. Review runs whose actor isn't a member of
+      the organization; scope the rule to the repository with the repo field.
+    logsource:
+      product: github
+      service: audit
+    fields_required: [action, event, actor, repo, workflow_run_id, head_branch]
+    detection:
+      selection:
+        action: workflows.created_workflow_run
+        event: "${triggers}"
+      condition: selection
+    falsepositives:
+      - Every run of this trigger matches, including maintainers' own; exclude organization members by actor, or use the rule for hunting
+      - Bots that comment on or open pull requests (dependabot, renovate)
+    level: low
+    test_events:
+      positive:
+        - action: workflows.created_workflow_run
+          event: "${trigger_example}"
+          actor: outside-contributor
+          repo: example-org/example-repo
+      negative:
+        - action: workflows.created_workflow_run
+          event: push
+          actor: maintainer
+          repo: example-org/example-repo
+        - action: workflows.completed_workflow_run
+          event: "${trigger_example}"
+          actor: outside-contributor
+          repo: example-org/example-repo
+
+  github-oidc-untrusted-trigger-cloudtrail:
+    date: "2026-10-12"
+    title: "AWS role assumed with a GitHub OIDC token from a pull-request run"
+    description: >-
+      CloudTrail AssumeRoleWithWebIdentity calls whose GitHub Actions OIDC
+      subject ends in ":pull_request", that is, the token was minted by a run
+      triggered by a pull request. AttackMap found a workflow that requests
+      an OIDC token (id-token: write) on a pull-request trigger (rule
+      ${rule_id}, ${location}). GitHub gives no OIDC token to pull_request
+      runs from forks, so the exposure is pull requests from branches in the
+      same repository: anyone who can push a branch (a contributor, a
+      compromised account or bot token) can run code holding the role. A
+      pull_request_target workflow that runs fork code with id-token: write
+      exposes it to forks as well. Restrict the role's trust policy to
+      branch or environment subjects. Blind spot: issue_comment and workflow_run runs get the
+      default branch's subject (ref:refs/heads/...), so their tokens look like
+      trusted ones here; fix those workflows instead.
+    logsource:
+      product: aws
+      service: cloudtrail
+    fields_required: [eventName, eventSource, userIdentity.type, userIdentity.identityProvider, userIdentity.userName, requestParameters.roleArn, sourceIPAddress]
+    detection:
+      selection:
+        eventSource: sts.amazonaws.com
+        eventName: AssumeRoleWithWebIdentity
+        userIdentity.identityProvider|contains: token.actions.githubusercontent.com
+        userIdentity.userName|endswith: ":pull_request"
+      condition: selection
+    falsepositives:
+      - Roles deliberately trusted for pull-request runs (read-only plan or test roles); exclude them by requestParameters.roleArn
+    level: high
+    test_events:
+      positive:
+        - eventSource: sts.amazonaws.com
+          eventName: AssumeRoleWithWebIdentity
+          userIdentity:
+            type: WebIdentityUser
+            identityProvider: arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com
+            userName: repo:example-org/example-repo:pull_request
+          requestParameters:
+            roleArn: arn:aws:iam::123456789012:role/deploy
+      negative:
+        - eventSource: sts.amazonaws.com
+          eventName: AssumeRoleWithWebIdentity
+          userIdentity:
+            type: WebIdentityUser
+            identityProvider: arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com
+            userName: repo:example-org/example-repo:ref:refs/heads/main
+          requestParameters:
+            roleArn: arn:aws:iam::123456789012:role/deploy
+
+data:
+  # Workflow rule id -> the triggers whose runs carry the risk, and a label.
+  # Kinds without an entry (unpinned actions, token permissions, curl | sh,
+  # script injection…) have no run-level signal in the audit log: the
+  # coverage table reports them as not covered.
+  triggers:
+    pr-target-checkout:
+      label: a pull_request_target workflow that checks out the pull request's code
+      events: [pull_request_target]
+    cache-poisoning-pr-target:
+      label: a pull_request_target workflow that writes a cache keyed on pull-request data
+      events: [pull_request_target]
+    issue-comment-pr-checkout:
+      label: an issue_comment workflow that checks out pull-request code
+      events: [issue_comment]
+    workflow-run-artifact-poisoning:
+      label: a workflow_run workflow that executes the triggering run's artifacts
+      events: [workflow_run]
+    self-hosted-pr:
+      label: a self-hosted runner on a pull-request trigger
+      events: [pull_request, pull_request_target]

attackmap/diagrams.py

@@ -0,0 +1,237 @@
+"""Mermaid + Graphviz diagram export (#49).
+
+Two shapes to export:
+
+- **Attack paths**  — each ``AttackPath`` becomes a top-to-bottom
+  flowchart with the existing step labels as node text. Steps chain in
+  order; the impact line lands in a separate impact node.
+- **Service topology** — the ``ServiceGraph`` produced by
+  ``build_service_graph`` becomes a directed graph with edge styles
+  distinguishing kinds (analyzer-declared / http-call / env-configured
+  / async-queue).
+
+Two output formats:
+
+- **Mermaid** — renders inline on GitHub, docs sites, and Notion.
+- **Graphviz DOT** — feed into ``dot -Tpng`` / ``dot -Tsvg`` for
+  slide-quality graphics.
+
+Nothing new is computed here; this is a pure output transform of
+existing model objects.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from .md import md_text, visible_text
+from .models import AttackPath
+from .topology import ServiceEdge, ServiceGraph
+
+# --- Mermaid ---------------------------------------------------------------
+
+
+def render_attack_paths_mermaid(paths: Iterable[AttackPath]) -> str:
+    """Return a Markdown document with one Mermaid flowchart per path."""
+    paths = list(paths)
+    if not paths:
+        return "# AttackMap — Attack paths\n\n_No attack paths surfaced in this scan._\n"
+
+    parts: list[str] = ["# AttackMap — Attack paths", ""]
+    for idx, path in enumerate(paths, start=1):
+        parts.append(f"## {idx}. {md_text(path.name)}")
+        parts.append("")
+        parts.append("```mermaid")
+        parts.append("flowchart TD")
+        node_ids = [_mermaid_node_id(idx, step_i) for step_i in range(len(path.steps) + 1)]
+        for step_i, step in enumerate(path.steps):
+            parts.append(f'  {node_ids[step_i]}["{_mermaid_text(step)}"]')
+        # Impact node — visually distinguished with a rectangular label.
+        impact_id = node_ids[-1]
+        parts.append(f'  {impact_id}["Impact: {_mermaid_text(path.impact)}"]')
+        parts.append(f"  class {impact_id} impact")
+        # Chain: n0 → n1 → n2 → ... → impact
+        if node_ids:
+            parts.append("  " + " --> ".join(node_ids))
+        parts.append("  classDef impact fill:#fee,stroke:#c33,color:#900;")
+        parts.append("```")
+        parts.append("")
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def render_topology_mermaid(graph: ServiceGraph) -> str:
+    """Return a Markdown document with one Mermaid graph for the topology."""
+    if not graph.nodes:
+        return "# AttackMap — Service topology\n\n_No services surfaced in this scan._\n"
+
+    parts: list[str] = [
+        "# AttackMap — Service topology",
+        "",
+        "```mermaid",
+        "flowchart LR",
+    ]
+
+    node_id_by_name: dict[str, str] = {}
+    for idx, node in enumerate(graph.nodes):
+        nid = f"S{idx}"
+        node_id_by_name[node.name] = nid
+        label = _mermaid_text(node.name)
+        if node.role and node.role != "service":
+            label = f"{label}<br/><i>{_mermaid_text(node.role)}</i>"
+        parts.append(f'  {nid}["{label}"]')
+
+    # Edges grouped by kind so the legend line makes sense.
+    for edge in graph.edges:
+        source = node_id_by_name.get(edge.source)
+        target = node_id_by_name.get(edge.target)
+        if source is None or target is None:
+            continue
+        parts.append(f"  {source} {_mermaid_edge(edge)} {target}")
+
+    # Style edges per-kind via linkStyle refs — Mermaid indexes edges in
+    # declaration order.
+    for idx, edge in enumerate(_valid_edges(graph, node_id_by_name)):
+        style = _mermaid_link_style(edge.kind)
+        if style:
+            parts.append(f"  linkStyle {idx} {style}")
+
+    parts.append("```")
+    parts.append("")
+    parts.append("_Edge kinds:_ **analyzer-declared** (solid), **http-call** (dashed), **env-configured** (dotted), **async-queue** (thick).")
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def _mermaid_edge(edge: ServiceEdge) -> str:
+    label = edge.evidence or edge.kind
+    label = _mermaid_text(label)
+    if edge.kind == "http-call":
+        return f'-. "{label}" .->'
+    if edge.kind == "env-configured":
+        return f'-. "{label}" .-'
+    if edge.kind == "async-queue":
+        return f'== "{label}" ==>'
+    # analyzer-declared / default
+    return f'-- "{label}" -->'
+
+
+def _mermaid_link_style(kind: str) -> str:
+    if kind == "http-call":
+        return "stroke:#2b7,stroke-dasharray:5 5;"
+    if kind == "env-configured":
+        return "stroke:#888,stroke-dasharray:2 4;"
+    if kind == "async-queue":
+        return "stroke:#a52,stroke-width:2px;"
+    return ""
+
+
+def _mermaid_node_id(path_idx: int, step_idx: int) -> str:
+    return f"P{path_idx}_{step_idx}"
+
+
+def _mermaid_escape(text: str) -> str:
+    """Escape characters Mermaid's flowchart parser hates inside labels."""
+    return (
+        text.replace("\\", "\\\\")
+        .replace('"', "'")
+        .replace("\n", " ")
+    )
+
+
+def _mermaid_text(text: str) -> str:
+    """A label made only of text. Attack-path steps and topology names and
+    evidence carry repo-derived strings, and Mermaid renders HTML in labels
+    (and Markdown in a label wrapped in backticks), so ``<``, ``>`` and
+    backticks become Mermaid entity codes (``#lt;``, ``#gt;``, ``#96;``) and
+    show as literal characters; control characters show as ``\\uXXXX``."""
+    return _mermaid_escape(visible_text(text)).replace("<", "#lt;").replace(">", "#gt;").replace("`", "#96;")
+
+
+# --- Graphviz DOT ----------------------------------------------------------
+
+
+def render_attack_paths_dot(paths: Iterable[AttackPath]) -> str:
+    """Return a Graphviz DOT document. One subgraph per attack path."""
+    paths = list(paths)
+    lines: list[str] = ["digraph AttackPaths {", "  rankdir=TB;", "  node [shape=box, style=rounded];"]
+    if not paths:
+        lines.append('  empty [label="No attack paths surfaced.", shape=note];')
+        lines.append("}")
+        return "\n".join(lines) + "\n"
+
+    for path_idx, path in enumerate(paths, start=1):
+        lines.append(f"  subgraph cluster_p{path_idx} {{")
+        lines.append(f'    label="{_dot_escape(path.name)}";')
+        lines.append('    style=rounded;')
+        node_ids = [f"p{path_idx}_{step_i}" for step_i in range(len(path.steps) + 1)]
+        for step_i, step in enumerate(path.steps):
+            lines.append(f'    {node_ids[step_i]} [label="{_dot_escape(step)}"];')
+        impact_id = node_ids[-1]
+        lines.append(
+            f'    {impact_id} [label="Impact: {_dot_escape(path.impact)}", '
+            f'style="rounded,filled", fillcolor="#fee", color="#c33"];'
+        )
+        for a, b in zip(node_ids, node_ids[1:]):
+            lines.append(f"    {a} -> {b};")
+        lines.append("  }")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def render_topology_dot(graph: ServiceGraph) -> str:
+    """Return a Graphviz DOT document for the service graph."""
+    lines: list[str] = ["digraph Topology {", "  rankdir=LR;", "  node [shape=box, style=rounded];"]
+    if not graph.nodes:
+        lines.append('  empty [label="No services surfaced.", shape=note];')
+        lines.append("}")
+        return "\n".join(lines) + "\n"
+
+    node_id_by_name: dict[str, str] = {}
+    for idx, node in enumerate(graph.nodes):
+        nid = f"s{idx}"
+        node_id_by_name[node.name] = nid
+        label = node.name if node.role in ("", "service") else f"{node.name}\\n[{node.role}]"
+        lines.append(f'  {nid} [label="{_dot_escape(label)}"];')
+
+    for edge in graph.edges:
+        source = node_id_by_name.get(edge.source)
+        target = node_id_by_name.get(edge.target)
+        if source is None or target is None:
+            continue
+        style = _dot_edge_style(edge.kind)
+        label = edge.evidence or edge.kind
+        lines.append(f'  {source} -> {target} [label="{_dot_escape(label)}"{style}];')
+
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def _dot_edge_style(kind: str) -> str:
+    if kind == "http-call":
+        return ', style=dashed, color="#2b7"'
+    if kind == "env-configured":
+        return ', style=dotted, color="#888"'
+    if kind == "async-queue":
+        return ', penwidth=2, color="#a52"'
+    return ""  # analyzer-declared → default
+
+
+def _dot_escape(text: str) -> str:
+    # Control characters as visible \uXXXX first, so a raw ESC from a scanned
+    # repo never reaches the terminal of whoever views the .dot file.
+    text = visible_text(text)
+    return text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+# --- Shared helper ---------------------------------------------------------
+
+
+def _valid_edges(graph: ServiceGraph, name_to_id: dict[str, str]) -> list[ServiceEdge]:
+    return [e for e in graph.edges if e.source in name_to_id and e.target in name_to_id]
+
+
+__all__ = [
+    "render_attack_paths_mermaid",
+    "render_attack_paths_dot",
+    "render_topology_mermaid",
+    "render_topology_dot",
+]