cloud-audit 2.1.0__tar.gz → 2.2.0__tar.gz

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-05-12
+
+### Added
+
+- **Threat Feed v1** — new `cloud-audit threat-feed` command and a dedicated
+  detector pipeline (`providers/aws/threat_feed/`) that flags ACTIVE abuse
+  indicators rather than misconfiguration. Each pattern has a versioned
+  `TF-XXX` ID, maps to the new `Category.THREAT`, and carries external
+  references (research reports, CVE links) on every Finding for credibility.
+  Rules pack version: **2026-Q2**.
+
+  Ten patterns shipped:
+
+  - `TF-001-ses-phishing-setup` (MEDIUM/HIGH) — SES email/domain identities
+    verified within the last 14 days, with severity escalating when an
+    out-of-sandbox account hosts a typosquat-style email identity that has
+    no matching domain identity. Tracks the Wiz May 2025 + BleepingComputer
+    May 2026 SES abuse campaigns.
+  - `TF-002-lambda-function-url-persistence` (HIGH/CRITICAL) — Lambda
+    functions exposed via `AuthType=NONE` Function URLs, escalating to
+    CRITICAL when the execution role grants admin-class permissions
+    (matching the role profile of the Nov-Dec 2025 cryptomining campaign).
+  - `TF-003-quarantine-policy` (CRITICAL) — IAM principals with
+    `AWSCompromisedKeyQuarantineV1/V2/V3` attached. AWS auto-attaches these
+    after detecting credential exposure (typically a public GitHub commit).
+  - `TF-004-trufflehog-ua-cloudtrail` (CRITICAL) — `sts:GetCallerIdentity`
+    calls in the last 24h whose user-agent matches known leaked-credentials
+    discovery scanners (TruffleHog, gitleaks, CloudGrappler, DetentionDodger,
+    NoseyParker). Confirmed credential validation by an external scanner.
+  - `TF-005-cryptomining-role` (HIGH/CRITICAL) — IAM roles created within
+    the last 48 hours that carry broad compute managed policies (EC2 Full,
+    PowerUser, Admin, ECS Full, Lambda Full). Escalates to CRITICAL when
+    the same role also has SES sending permissions (mining + email-spam
+    combo from the documented late-2025 campaign cluster).
+  - `TF-006-mmdsv1-in-use` (HIGH/CRITICAL) — EC2 instances where
+    `HttpTokens != required` (IMDSv1 still callable) and Bedrock AgentCore
+    agents on `metadataVersion=v1` (CRITICAL — addresses Unit 42 'Cracks in
+    the Bedrock' research and the Feb 2026 MMDSv2 default).
+  - `TF-007-whoami-confusion` (MEDIUM) — IAM roles trusted by CI/CD
+    identities (codebuild service principals, GitHub OIDC, GitLab OIDC,
+    Buildkite federation) that have a broad EC2 managed policy attached —
+    the precondition for the Datadog Feb 2025 whoAMI confusion attack.
+  - `TF-008-cloudtrail-tampering` (HIGH/CRITICAL) — CloudTrail trails with
+    `IsLogging=False` (CRITICAL — canonical post-credential-theft attacker
+    behaviour, AiTM phishing follow-on per Datadog March 2026) or with a
+    populated `LatestDeliveryError` (HIGH — S3 destination broken).
+  - `TF-009-roles-anywhere-abuse` (HIGH/MEDIUM) — IAM Roles Anywhere trust
+    anchors with `sourceType=CERTIFICATE_BUNDLE` instead of the recommended
+    AWS_ACM_PCA. Anyone able to issue a chain-valid cert can mint AWS
+    credentials (fwd:cloudsec 2025 'Let's Encrypt for AWS Console').
+  - `TF-010-datazone-overgrant` (HIGH) — `AmazonDataZoneFullAccess` attached
+    to non-admin principals (the "easy" onboarding policy that bridges
+    identity, Glue catalog, and S3 storage in a single grant).
+
+  CLI: `cloud-audit threat-feed [--list] [--pattern <id>] [--regions ...]
+  [--profile ...] [--threat-feed-version 2026-Q2]`. Exits 1 when CRITICAL
+  or HIGH detected (CI gate friendly). Patterns also surface in standard
+  `cloud-audit scan --categories threat` output (JSON, SARIF, HTML).
+
+### Changed
+
+- `Category` enum gains `THREAT` value for active-abuse findings (separate
+  from `SECURITY` misconfiguration).
+- `Finding` model gains `threat_pattern_id: str | None` and
+  `references: list[str]` for backing research links.
+- 23rd registered AWS check module (`threat_feed`) loaded by `AWSProvider`.
+
+### Tests
+
+- 638 -> 742 (+104). Each pattern ships 9-12 unit tests covering positive
+  detection, negative cases, false-positive guards, severity escalation,
+  multi-resource aggregation, AccessDenied resilience, and metadata
+  exposure.
+
 ## [2.1.0] - 2026-04-28
 
 ### Added

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cloud-audit
-Version: 2.1.0
-Summary: Open-source AWS security scanner with IAM escalation detection, What-If simulator, security trends, AI-SPM (Bedrock/SageMaker), 6 compliance frameworks, 31 attack chain rules, breach cost estimation, and MCP server. 94 checks across 23 services. Every finding includes CLI + Terraform remediation.
+Version: 2.2.0
+Summary: Open-source AWS security scanner. Threat Feed v1 (10 active-abuse patterns from 2025-2026 incidents), 64 IAM escalation methods, What-If simulator, security trends, AI-SPM (Bedrock/SageMaker), 6 compliance frameworks, 31 attack chain rules, breach cost estimation, and MCP server. Every finding includes CLI + Terraform remediation.
 Project-URL: Homepage, https://haitmg.pl/cloud-audit/
 Project-URL: Documentation, https://haitmg.pl/cloud-audit/
 Project-URL: Source, https://github.com/gebalamariusz/cloud-audit
@@ -83,6 +83,7 @@ Description-Content-Type: text/markdown
   <a href="https://haitmg.pl/cloud-audit/compliance/overview/">Compliance</a> -
   <a href="https://haitmg.pl/cloud-audit/features/attack-chains/">Attack Chains</a> -
   <a href="https://haitmg.pl/cloud-audit/features/iam-escalation/">IAM Escalation</a> -
+  <a href="https://haitmg.pl/cloud-audit/features/threat-feed/">Threat Feed</a> -
   <a href="https://haitmg.pl/cloud-audit/features/simulate/">Simulator</a> -
   <a href="https://haitmg.pl/cloud-audit/features/mcp-server/">MCP Server</a>
 </p>
@@ -100,6 +101,21 @@ Uses your default AWS credentials and region. Try without an AWS account:
 cloud-audit demo
 ```
 
+### NEW in v2.2: Threat Feed
+
+Detect ACTIVE abuse patterns from 2025-2026 incidents (cryptomining campaigns,
+SES phishing setup, leaked-credential scanner activity, AgentCore CVEs):
+
+```bash
+cloud-audit threat-feed              # scan all 10 patterns
+cloud-audit threat-feed --list       # show registered patterns
+cloud-audit threat-feed --pattern aws-tf-003   # one pattern only
+```
+
+Each pattern carries external research references (Wiz, Datadog Security Labs,
+Unit 42, Permiso) on every finding. Exit code 1 when CRITICAL/HIGH detected
+(CI gate friendly). See [Threat Feed docs](https://haitmg.pl/cloud-audit/features/threat-feed/).
+
 ---
 
 ## Why It's Different

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/README.md

@@ -36,6 +36,7 @@
   <a href="https://haitmg.pl/cloud-audit/compliance/overview/">Compliance</a> -
   <a href="https://haitmg.pl/cloud-audit/features/attack-chains/">Attack Chains</a> -
   <a href="https://haitmg.pl/cloud-audit/features/iam-escalation/">IAM Escalation</a> -
+  <a href="https://haitmg.pl/cloud-audit/features/threat-feed/">Threat Feed</a> -
   <a href="https://haitmg.pl/cloud-audit/features/simulate/">Simulator</a> -
   <a href="https://haitmg.pl/cloud-audit/features/mcp-server/">MCP Server</a>
 </p>
@@ -53,6 +54,21 @@ Uses your default AWS credentials and region. Try without an AWS account:
 cloud-audit demo
 ```
 
+### NEW in v2.2: Threat Feed
+
+Detect ACTIVE abuse patterns from 2025-2026 incidents (cryptomining campaigns,
+SES phishing setup, leaked-credential scanner activity, AgentCore CVEs):
+
+```bash
+cloud-audit threat-feed              # scan all 10 patterns
+cloud-audit threat-feed --list       # show registered patterns
+cloud-audit threat-feed --pattern aws-tf-003   # one pattern only
+```
+
+Each pattern carries external research references (Wiz, Datadog Security Labs,
+Unit 42, Permiso) on every finding. Exit code 1 when CRITICAL/HIGH detected
+(CI gate friendly). See [Threat Feed docs](https://haitmg.pl/cloud-audit/features/threat-feed/).
+
 ---
 
 ## Why It's Different

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/mkdocs.yml

@@ -60,6 +60,7 @@ nav:
   - Features:
     - Attack Chains: features/attack-chains.md
     - IAM Privilege Escalation: features/iam-escalation.md
+    - Threat Feed: features/threat-feed.md
     - What-If Simulator: features/simulate.md
     - Security Posture Trend: features/trend.md
     - AI-SPM (Bedrock/SageMaker): features/ai-spm.md

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cloud-audit"
-version = "2.1.0"
-description = "Open-source AWS security scanner with IAM escalation detection, What-If simulator, security trends, AI-SPM (Bedrock/SageMaker), 6 compliance frameworks, 31 attack chain rules, breach cost estimation, and MCP server. 94 checks across 23 services. Every finding includes CLI + Terraform remediation."
+version = "2.2.0"
+description = "Open-source AWS security scanner. Threat Feed v1 (10 active-abuse patterns from 2025-2026 incidents), 64 IAM escalation methods, What-If simulator, security trends, AI-SPM (Bedrock/SageMaker), 6 compliance frameworks, 31 attack chain rules, breach cost estimation, and MCP server. Every finding includes CLI + Terraform remediation."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -81,6 +81,13 @@ select = ["E", "F", "I", "N", "W", "UP", "S", "B", "A", "C4", "SIM", "TCH", "RUF
 "src/cloud_audit/reports/compliance_markdown.py" = ["E501"]
 "src/cloud_audit/cli.py" = ["TC003"]
 "src/cloud_audit/mcp_server.py" = ["TC003"]
+# Threat-feed modules and tests intentionally use boto3-style CamelCase
+# kwargs (UserName, RoleName, FunctionName, EmailIdentity) to match the
+# AWS API surface they wrap. N803 (lower_snake_case argument) is wrong here.
+# Inner exception classes used to simulate boto3 errors don't need the
+# Error suffix N818 mandates. Lambda/SES helpers also use Optional implicitly.
+"src/cloud_audit/providers/aws/threat_feed/*.py" = ["N803", "N818", "RUF013", "E501", "S112"]
+"tests/aws/threat_feed/*.py" = ["S101", "N803", "N806", "N818", "RUF013", "E501", "TC003", "E402"]
 "tests/**" = ["S101", "TC003", "E402"]
 
 [tool.mypy]

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/src/cloud_audit/cli.py

@@ -1448,6 +1448,145 @@ def simulate(
     console.print()
 
 
+@app.command(name="threat-feed")
+def threat_feed_cmd(
+    profile: Annotated[str | None, typer.Option("--profile", help="AWS profile")] = None,
+    regions: Annotated[
+        str | None,
+        typer.Option("--regions", "-r", help="Comma-separated regions, or 'all' for every enabled region"),
+    ] = None,
+    pattern: Annotated[
+        str | None,
+        typer.Option("--pattern", help="Run only one pattern (e.g. aws-tf-003); default = all"),
+    ] = None,
+    list_patterns: Annotated[
+        bool,
+        typer.Option("--list", help="List registered patterns and exit (no scan)"),
+    ] = False,
+    threat_feed_version: Annotated[
+        str | None,
+        typer.Option("--threat-feed-version", help="Pin a rules-pack version (informational, default = current)"),
+    ] = None,
+) -> None:
+    """Detect ACTIVE abuse patterns from 2025-2026 threat reports.
+
+    Distinct from regular `scan`: looks for indicators that an attacker has ALREADY
+    acted on the account (quarantine policies AWS attached after credential leak,
+    public Lambda URLs created as persistence, DataZone over-grants, etc.) rather
+    than mere misconfigurations.
+
+    Examples:
+        cloud-audit threat-feed                       # scan all patterns
+        cloud-audit threat-feed --pattern aws-tf-003  # one pattern only
+        cloud-audit threat-feed --list                # show registered patterns
+    """
+    from cloud_audit.providers.aws import threat_feed as tf_module
+
+    if list_patterns:
+        table = Table(title=f"Registered threat patterns (rules pack {tf_module.THREAT_FEED_VERSION})")
+        table.add_column("Pattern ID", style="bold")
+        table.add_column("Check ID")
+        table.add_column("Severity")
+        table.add_column("Name")
+        table.add_column("Doc")
+        for p in tf_module.list_patterns():
+            sev_color = SEVERITY_COLORS.get(Severity(p["severity"]), "white")
+            table.add_row(
+                p["pattern_id"],
+                p["check_id"],
+                f"[{sev_color}]{p['severity'].upper()}[/{sev_color}]",
+                p["name"],
+                p["doc_url"],
+            )
+        console.print(table)
+        console.print(f"\n[dim]{len(tf_module.list_patterns())} patterns registered.[/dim]")
+        return
+
+    active_version = threat_feed_version or tf_module.THREAT_FEED_VERSION
+    if threat_feed_version and threat_feed_version != tf_module.THREAT_FEED_VERSION:
+        console.print(
+            f"[yellow]Note: requested rules pack '{threat_feed_version}' differs from installed "
+            f"'{tf_module.THREAT_FEED_VERSION}'. Pinning is informational in this build.[/yellow]"
+        )
+
+    from cloud_audit.providers.aws.provider import AWSProvider
+
+    region_list = None
+    if regions:
+        region_list = ["all"] if regions.strip() == "all" else [r.strip() for r in regions.split(",")]
+
+    try:
+        provider = AWSProvider(profile=profile, regions=region_list)
+    except Exception as exc:
+        console.print(f"[red]Failed to initialize AWS provider: {exc}[/red]")
+        raise typer.Exit(2) from exc
+
+    threat_checks = [c for c in provider.get_checks() if getattr(c, "category", None) and c.category.value == "threat"]
+    if pattern:
+        threat_checks = [c for c in threat_checks if c.check_id == pattern]
+        if not threat_checks:
+            console.print(f"[red]No registered threat pattern with check_id '{pattern}'.[/red]")
+            console.print("Run [cyan]cloud-audit threat-feed --list[/cyan] to see available patterns.")
+            raise typer.Exit(2)
+
+    console.print(
+        Panel(
+            f"Scanning [bold]{len(threat_checks)}[/bold] threat patterns (rules pack [cyan]{active_version}[/cyan])",
+            title="[bold]Threat Feed[/bold]",
+            border_style="magenta",
+        )
+    )
+
+    all_findings: list[Finding] = []
+    errors: list[tuple[str, str]] = []
+    for check in threat_checks:
+        try:
+            result = check()
+        except Exception as exc:  # defensive - check should already capture
+            errors.append((check.check_id, str(exc)))
+            continue
+        if result.error:
+            errors.append((check.check_id, result.error))
+        all_findings.extend(result.findings)
+
+    if errors:
+        console.print()
+        for check_id, err in errors:
+            console.print(f"[yellow]! {check_id}: {err}[/yellow]")
+
+    if not all_findings:
+        console.print("\n[green]No active abuse patterns detected.[/green]\n")
+        raise typer.Exit(0)
+
+    table = Table(title=f"Detected threat patterns ({len(all_findings)} findings)", show_lines=True)
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Pattern", style="bold")
+    table.add_column("Resource")
+    table.add_column("Region")
+    table.add_column("References")
+
+    for f in sorted(all_findings, key=lambda x: list(SEVERITY_COLORS).index(x.severity)):
+        sev_color = SEVERITY_COLORS[f.severity]
+        refs = "\n".join(f.references[:2]) if f.references else "-"
+        table.add_row(
+            f"[{sev_color}]{f.severity.value.upper()}[/{sev_color}]",
+            f"{f.threat_pattern_id or f.check_id}\n[dim]{rich_escape(f.title)}[/dim]",
+            rich_escape(f.resource_id),
+            f.region,
+            refs,
+        )
+
+    console.print(table)
+    console.print(
+        "\n[dim]Use [cyan]cloud-audit scan --categories threat -o json[/cyan] for machine-readable output "
+        "(includes full remediation + references).[/dim]\n"
+    )
+
+    # Exit 1 when CRITICAL/HIGH detected (CI gate)
+    blocking = [f for f in all_findings if f.severity in (Severity.CRITICAL, Severity.HIGH)]
+    raise typer.Exit(1 if blocking else 0)
+
+
 @app.command()
 def version() -> None:
     """Show version."""

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/src/cloud_audit/models.py

@@ -22,6 +22,7 @@ class Category(str, Enum):
     COST = "cost"
     RELIABILITY = "reliability"
     PERFORMANCE = "performance"
+    THREAT = "threat"
 
 
 class Effort(str, Enum):
@@ -75,6 +76,14 @@ class Finding(BaseModel):
     remediation: Remediation | None = Field(default=None, description="Structured remediation details")
     compliance_refs: list[str] = Field(default_factory=list, description="Compliance references, e.g. ['CIS 1.5']")
     cost_estimate: CostEstimateData | None = Field(default=None, description="Estimated breach cost range")
+    threat_pattern_id: str | None = Field(
+        default=None,
+        description="Threat feed pattern identifier, e.g. 'TF-003-quarantine-policy' (None for regular checks)",
+    )
+    references: list[str] = Field(
+        default_factory=list,
+        description="External references (research reports, CVE links, blog posts) backing this finding",
+    )
 
 
 class CheckResult(BaseModel):

{cloud_audit-2.1.0 → cloud_audit-2.2.0}/src/cloud_audit/providers/aws/provider.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 import boto3
 from botocore.config import Config
 
+from cloud_audit.providers.aws import threat_feed
 from cloud_audit.providers.aws.checks import (
     account,
     backup,
@@ -65,6 +66,7 @@ _CHECK_MODULES = [
     waf,
     bedrock,
     sagemaker,
+    threat_feed,
 ]
 
 

cloud_audit-2.2.0/src/cloud_audit/providers/aws/threat_feed/__init__.py

@@ -0,0 +1,105 @@
+"""Threat Feed - active abuse pattern detectors.
+
+Each pattern in this package detects an attack technique observed in real-world
+2025-2026 incidents (cryptomining campaigns, SES phishing, leaked credentials,
+AgentCore vulnerabilities). Patterns are versioned via THREAT_FEED_VERSION so
+operators can pin a known rules pack.
+
+Patterns vs regular checks:
+    - Regular checks (providers/aws/checks/) detect MISCONFIGURATION
+    - Threat patterns (this package) detect ACTIVE ABUSE INDICATORS or
+      conditions an attacker exploited in a documented incident.
+
+Each pattern produces standard Finding objects with:
+    - category=Category.THREAT
+    - threat_pattern_id="TF-XXX-name"
+    - references=[<URL to research report or CVE>]
+
+Adding a new pattern:
+    1. Create src/cloud_audit/providers/aws/threat_feed/<name>.py
+    2. Implement: def detect(provider) -> CheckResult
+    3. Register in _PATTERN_MODULES below
+    4. Add tests in tests/aws/threat_feed/test_<name>.py
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cloud_audit.models import Category
+from cloud_audit.providers.aws.threat_feed import (
+    cloudtrail_tampering,
+    cryptomining_role,
+    datazone_overgrant,
+    lambda_function_url,
+    mmdsv1_in_use,
+    quarantine_policy,
+    roles_anywhere_abuse,
+    ses_phishing,
+    trufflehog_ua,
+    whoami_confusion,
+)
+from cloud_audit.providers.base import make_check
+
+if TYPE_CHECKING:
+    from cloud_audit.providers.aws.provider import AWSProvider
+    from cloud_audit.providers.base import CheckFn
+
+THREAT_FEED_VERSION = "2026-Q2"
+"""Versioned rules pack identifier - bump when patterns added/removed/changed.
+
+Operators pin via `cloud-audit threat-feed --threat-feed-version 2026-Q2`
+to get reproducible scans across releases.
+"""
+
+_PATTERN_MODULES = [
+    ses_phishing,
+    lambda_function_url,
+    quarantine_policy,
+    trufflehog_ua,
+    cryptomining_role,
+    mmdsv1_in_use,
+    whoami_confusion,
+    cloudtrail_tampering,
+    roles_anywhere_abuse,
+    datazone_overgrant,
+]
+"""Registry of all threat feed pattern modules.
+
+Order matters for output stability - keep it deterministic.
+New patterns: append to the end so existing TF-IDs remain stable.
+"""
+
+
+def get_checks(provider: AWSProvider) -> list[CheckFn]:
+    """Return all threat feed pattern check functions bound to the provider.
+
+    Each pattern module exposes:
+        - detect(provider) -> CheckResult
+        - PATTERN_ID: str  (e.g. "TF-003-quarantine-policy")
+        - CHECK_ID: str    (e.g. "aws-tf-003")
+    """
+    checks: list[CheckFn] = []
+    for module in _PATTERN_MODULES:
+        check = make_check(
+            module.detect,
+            provider,
+            check_id=module.CHECK_ID,
+            category=Category.THREAT,
+        )
+        checks.append(check)
+    return checks
+
+
+def list_patterns() -> list[dict[str, str]]:
+    """Return metadata for all registered patterns - used by CLI list/help."""
+    return [
+        {
+            "pattern_id": m.PATTERN_ID,
+            "check_id": m.CHECK_ID,
+            "name": m.PATTERN_NAME,
+            "severity": m.PATTERN_SEVERITY.value,
+            "doc_url": m.DOC_URL,
+        }
+        for m in _PATTERN_MODULES
+    ]

cloud_audit-2.2.0/src/cloud_audit/providers/aws/threat_feed/cloudtrail_tampering.py

@@ -0,0 +1,195 @@
+"""TF-008: CloudTrail tampering precursors.
+
+After compromising credentials, attackers commonly try to blind CloudTrail
+before doing further damage so subsequent activity is not logged. AWS has
+documented this pattern repeatedly (the AiTM phishing follow-on actions
+documented by Datadog Security Labs in March 2026 included CloudTrail stop
+attempts as the second-stage action).
+
+We surface tampering PRECURSORS - signals that may indicate either active
+tampering OR a misconfiguration that achieves the same blind-spot effect:
+- Trails that exist but have IsLogging=False (intentionally stopped)
+- Trails with LatestDeliveryError populated (S3 destination broken / bucket
+  removed - whether by attacker or by mistake, your evidence is gone)
+- Trails that lack IncludeManagementEvents in their event selectors
+  (control-plane API calls bypass the trail entirely)
+
+The cloud-audit `cloudtrail.py` checks cover MISCONFIGURATION (trail not
+enabled at all, log file validation off). This pattern covers ACTIVE
+tampering / state-drift signals on existing trails.
+
+References:
+    - https://securitylabs.datadoghq.com/articles/behind-the-console-aws-aitm-phishing-campaign/
+    - https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-faqs.html
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cloud_audit.models import Category, CheckResult, Effort, Finding, Remediation, Severity
+
+if TYPE_CHECKING:
+    from cloud_audit.providers.aws.provider import AWSProvider
+
+
+PATTERN_ID = "TF-008-cloudtrail-tampering"
+CHECK_ID = "aws-tf-008"
+PATTERN_NAME = "CloudTrail tampering precursor (logging stopped or delivery failing)"
+PATTERN_SEVERITY = Severity.HIGH
+DOC_URL = "https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-faqs.html"
+
+_REFERENCES = [
+    "https://securitylabs.datadoghq.com/articles/behind-the-console-aws-aitm-phishing-campaign/",
+    "https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-faqs.html",
+]
+
+
+def _build_logging_stopped_finding(trail_name: str, trail_arn: str, region: str) -> Finding:
+    return Finding(
+        check_id=CHECK_ID,
+        title=f"CloudTrail '{trail_name}' has IsLogging=False (logging stopped)",
+        severity=Severity.CRITICAL,
+        category=Category.THREAT,
+        resource_type="AWS::CloudTrail::Trail",
+        resource_id=trail_arn,
+        region=region,
+        description=(
+            f"Trail '{trail_name}' exists but is currently NOT logging. Either someone "
+            "called cloudtrail:StopLogging recently (canonical attacker behaviour after "
+            "credential theft - documented by Datadog Security Labs March 2026 in the "
+            "AWS AiTM phishing campaign) or it was disabled administratively and never "
+            "re-enabled. Either way, your CloudTrail evidence path is broken right now."
+        ),
+        recommendation=(
+            "(1) Re-enable logging immediately if this is unexpected. (2) Audit who "
+            "called StopLogging and when - the management event for that call is itself "
+            "logged (in another trail or, before this trail was stopped, in this one). "
+            "(3) Add an EventBridge rule that fires on cloudtrail:StopLogging and pages "
+            "your on-call. (4) Add a Service Control Policy (SCP) that denies "
+            "cloudtrail:StopLogging and cloudtrail:DeleteTrail to all non-break-glass "
+            "principals."
+        ),
+        remediation=Remediation(
+            cli=(
+                f"# 1) Restore logging immediately:\n"
+                f"aws cloudtrail start-logging --name {trail_name} --region {region}\n"
+                f"\n# 2) Find who stopped it (look in any other active trail):\n"
+                f"aws cloudtrail lookup-events \\\n"
+                f"  --lookup-attributes AttributeKey=EventName,AttributeValue=StopLogging \\\n"
+                f"  --region {region}\n"
+                f"\n# 3) Add an EventBridge rule for future visibility:\n"
+                f"aws events put-rule --name detect-cloudtrail-stop \\\n"
+                f'  --event-pattern \'{{"source":["aws.cloudtrail"],"detail-type":"AWS API Call via CloudTrail",'
+                f'"detail":{{"eventName":["StopLogging","DeleteTrail"]}}}}\''
+            ),
+            terraform=(
+                'resource "aws_cloudwatch_event_rule" "detect_trail_stop" {\n'
+                '  name        = "detect-cloudtrail-tampering"\n'
+                '  description = "Alert on CloudTrail stop or delete"\n'
+                "  event_pattern = jsonencode({\n"
+                '    source      = ["aws.cloudtrail"]\n'
+                '    "detail-type" = ["AWS API Call via CloudTrail"]\n'
+                "    detail = {\n"
+                '      eventName = ["StopLogging", "DeleteTrail", "PutEventSelectors", "UpdateTrail"]\n'
+                "    }\n"
+                "  })\n"
+                "}"
+            ),
+            doc_url=DOC_URL,
+            effort=Effort.LOW,
+        ),
+        threat_pattern_id=PATTERN_ID,
+        references=_REFERENCES,
+    )
+
+
+def _build_delivery_error_finding(trail_name: str, trail_arn: str, region: str, error: str) -> Finding:
+    return Finding(
+        check_id=CHECK_ID,
+        title=f"CloudTrail '{trail_name}' has S3 delivery error - evidence path is broken",
+        severity=Severity.HIGH,
+        category=Category.THREAT,
+        resource_type="AWS::CloudTrail::Trail",
+        resource_id=trail_arn,
+        region=region,
+        description=(
+            f"Trail '{trail_name}' is technically logging but its S3 delivery is failing. "
+            f"LatestDeliveryError reports: '{error}'. Common causes are an attacker "
+            "who deleted the destination bucket (or its bucket policy), bucket KMS "
+            "key removal, or accidental cross-account permission revocation. Result is "
+            "the same: events are dropped, your evidence is incomplete."
+        ),
+        recommendation=(
+            "Investigate the underlying bucket/KMS/policy state. After fixing, verify "
+            "with `get-trail-status` that LatestDeliveryError is no longer set."
+        ),
+        remediation=Remediation(
+            cli=(
+                f"aws cloudtrail get-trail-status --name {trail_name} --region {region}\n"
+                f"# Then inspect the destination bucket policy and KMS key state."
+            ),
+            terraform="# Diagnostic only - fix is on the destination bucket / KMS key.",
+            doc_url=DOC_URL,
+            effort=Effort.MEDIUM,
+        ),
+        threat_pattern_id=PATTERN_ID,
+        references=_REFERENCES,
+    )
+
+
+def _scan_region(provider: AWSProvider, region: str) -> tuple[int, list[Finding]]:
+    ct = provider.client("cloudtrail", region_name=region)
+    findings: list[Finding] = []
+    scanned = 0
+
+    try:
+        trails = ct.describe_trails(includeShadowTrails=False).get("trailList", [])
+    except Exception as exc:
+        code = getattr(exc, "response", {}).get("Error", {}).get("Code", "")
+        if code in ("AccessDeniedException", "UnrecognizedClientException"):
+            return 0, []
+        raise
+
+    for trail in trails:
+        # Skip shadow trails (multi-region trails appear in every region; we want home only)
+        if trail.get("HomeRegion") and trail.get("HomeRegion") != region:
+            continue
+        scanned += 1
+        trail_name = trail.get("Name", "")
+        trail_arn = trail.get("TrailARN", "")
+        try:
+            status = ct.get_trail_status(Name=trail_arn or trail_name)
+        except Exception as exc:
+            code = getattr(exc, "response", {}).get("Error", {}).get("Code", "")
+            if code in ("AccessDenied", "TrailNotFoundException"):
+                continue
+            raise
+
+        is_logging = bool(status.get("IsLogging", False))
+        delivery_error = status.get("LatestDeliveryError") or ""
+
+        if not is_logging:
+            findings.append(_build_logging_stopped_finding(trail_name, trail_arn, region))
+            # Don't double-flag the same trail with delivery error if logging is stopped
+            continue
+
+        if delivery_error:
+            findings.append(_build_delivery_error_finding(trail_name, trail_arn, region, delivery_error))
+
+    return scanned, findings
+
+
+def detect(provider: AWSProvider) -> CheckResult:
+    """Scan all regions for CloudTrail trails showing tampering precursors."""
+    result = CheckResult(check_id=CHECK_ID, check_name=PATTERN_NAME)
+
+    try:
+        for region in provider.regions:
+            scanned, findings = _scan_region(provider, region)
+            result.resources_scanned += scanned
+            result.findings.extend(findings)
+    except Exception as e:
+        result.error = str(e)
+
+    return result