agentveil-posture 0.1.0__py3-none-any.whl

agentveil_posture/__init__.py

@@ -0,0 +1,6 @@
+"""AgentVeil Posture static scanner."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

agentveil_posture/cli.py

@@ -0,0 +1,98 @@
+"""Command-line interface for AgentVeil Posture."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Sequence
+
+from agentveil_posture.report import SEVERITIES, Finding, PostureReport
+from agentveil_posture.scanner import ScanError, scan_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentveil",
+        description="AgentVeil developer tools.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    posture_parser = subparsers.add_parser(
+        "posture",
+        help="Run static posture checks.",
+    )
+    posture_subparsers = posture_parser.add_subparsers(
+        dest="posture_command",
+        required=True,
+    )
+
+    scan_parser = posture_subparsers.add_parser(
+        "scan",
+        help="Scan a project and write a posture report.",
+    )
+    scan_parser.add_argument(
+        "--path",
+        default=".",
+        help="Project path to scan. Defaults to the current directory.",
+    )
+    scan_parser.add_argument(
+        "--output",
+        required=True,
+        help="Path where the report will be written.",
+    )
+    scan_parser.add_argument(
+        "--format",
+        choices=("json", "sarif"),
+        default="json",
+        help="Report format to write. Defaults to json.",
+    )
+    scan_parser.add_argument(
+        "--fail-on",
+        choices=SEVERITIES,
+        default=None,
+        help="Exit 1 when findings at or above this severity are present.",
+    )
+    scan_parser.set_defaults(handler=_handle_posture_scan)
+
+    return parser
+
+
+def _finding_meets_threshold(finding: Finding, threshold: str) -> bool:
+    return SEVERITIES.index(finding.severity) <= SEVERITIES.index(threshold)
+
+
+def _report_meets_threshold(report: PostureReport, threshold: str | None) -> bool:
+    if threshold is None:
+        return False
+    return any(_finding_meets_threshold(finding, threshold) for finding in report.findings)
+
+
+def _handle_posture_scan(args: argparse.Namespace) -> int:
+    try:
+        report = scan_path(Path(args.path))
+        if args.format == "json":
+            output = report.to_json()
+        else:
+            output = json.dumps(report.to_sarif(), indent=2, sort_keys=True) + "\n"
+        Path(args.output).write_text(output, encoding="utf-8")
+        if _report_meets_threshold(report, args.fail_on):
+            return 1
+        return 0
+    except (OSError, ScanError) as exc:
+        print(f"agentveil posture scan: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.error("missing command")
+    return int(handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentveil_posture/report.py

@@ -0,0 +1,210 @@
+"""Versioned JSON report model for AgentVeil Posture."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+import hashlib
+import json
+
+
+REPORT_VERSION = "0.1"
+SCANNER_VERSION = "agentveil-posture/0.1.0"
+SEVERITIES = ("critical", "high", "medium", "low", "info")
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+SARIF_VERSION = "2.1.0"
+SEVERITY_TO_SARIF_LEVEL = {
+    "critical": "error",
+    "high": "error",
+    "medium": "warning",
+    "low": "note",
+    "info": "note",
+}
+SEVERITY_TO_SECURITY_SEVERITY = {
+    "critical": "9.5",
+    "high": "8.0",
+    "medium": "5.0",
+    "low": "3.0",
+    "info": "0.0",
+}
+RULE_DESCRIPTORS = {
+    "bypass.direct_github_token": {
+        "short": "Direct GitHub token capability",
+        "full": "Flags direct GitHub token references in workflows or agent manifests.",
+        "help": "https://github.com/agentveil-protocol/agentveil-posture#triaging-findings",
+    },
+    "workflow.deploy_without_approval": {
+        "short": "Deployment without approval gate",
+        "full": "Flags deploy, release, or publish workflow steps without an approval signal.",
+        "help": "https://github.com/agentveil-protocol/agentveil-posture#triaging-findings",
+    },
+    "workflow.pull_request_target_secrets_risk": {
+        "short": "Privileged pull_request_target risk",
+        "full": "Flags pull_request_target workflows that combine privileged context with checkout, run, or secrets.",
+        "help": "https://github.com/agentveil-protocol/agentveil-posture#triaging-findings",
+    },
+    "tool.shell_without_approval": {
+        "short": "Shell-capable tool without approval",
+        "full": "Flags agent tool manifests that expose shell execution without an approval flag.",
+        "help": "https://github.com/agentveil-protocol/agentveil-posture#triaging-findings",
+    },
+    "identity.private_key_unencrypted": {
+        "short": "Unencrypted private key file",
+        "full": "Flags committed PEM private key files that appear to be unencrypted.",
+        "help": "https://github.com/agentveil-protocol/agentveil-posture#triaging-findings",
+    },
+}
+
+
+def utc_now_iso() -> str:
+    return (
+        datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    severity: str
+    file: str
+    line: int | None
+    message: str
+    remediation: str
+
+    def __post_init__(self) -> None:
+        if self.severity not in SEVERITIES:
+            raise ValueError(f"unknown severity: {self.severity}")
+        category, separator, name = self.rule_id.partition(".")
+        if not category or separator != "." or not name:
+            raise ValueError(f"invalid rule_id: {self.rule_id}")
+        allowed = set("abcdefghijklmnopqrstuvwxyz0123456789_")
+        if not set(category) <= allowed or not set(name) <= allowed:
+            raise ValueError(f"invalid rule_id: {self.rule_id}")
+        if (
+            self.file.startswith("/")
+            or self.file.startswith("\\\\")
+            or (len(self.file) >= 2 and self.file[1] == ":")
+        ):
+            raise ValueError("finding file must be repository-relative")
+
+
+@dataclass(frozen=True)
+class Summary:
+    by_severity: dict[str, int]
+    total: int
+
+
+@dataclass(frozen=True)
+class PostureReport:
+    report_version: str
+    scanner_version: str
+    scanned_at: str
+    scanned_path: str
+    findings: list[Finding] = field(default_factory=list)
+    summary: Summary = field(default_factory=lambda: empty_summary())
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, sort_keys=True) + "\n"
+
+    def to_sarif(self) -> dict[str, object]:
+        rule_ids = sorted(RULE_DESCRIPTORS)
+        rule_index = {rule_id: index for index, rule_id in enumerate(rule_ids)}
+        return {
+            "$schema": SARIF_SCHEMA,
+            "version": SARIF_VERSION,
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "AgentVeil Posture",
+                            "informationUri": "https://github.com/agentveil-protocol/agentveil-posture",
+                            "semanticVersion": "0.1.0",
+                            "rules": [_sarif_rule(rule_id) for rule_id in rule_ids],
+                        }
+                    },
+                    "results": [
+                        _sarif_result(finding, rule_index[finding.rule_id])
+                        for finding in self.findings
+                    ],
+                }
+            ],
+        }
+
+
+def empty_summary() -> Summary:
+    return Summary(by_severity={severity: 0 for severity in SEVERITIES}, total=0)
+
+
+def empty_report(scanned_path: str) -> PostureReport:
+    return build_report(scanned_path, [])
+
+
+def build_report(scanned_path: str, findings: list[Finding]) -> PostureReport:
+    by_severity = {severity: 0 for severity in SEVERITIES}
+    for finding in findings:
+        by_severity[finding.severity] += 1
+    return PostureReport(
+        report_version=REPORT_VERSION,
+        scanner_version=SCANNER_VERSION,
+        scanned_at=utc_now_iso(),
+        scanned_path=scanned_path,
+        findings=findings,
+        summary=Summary(by_severity=by_severity, total=len(findings)),
+    )
+
+
+def _sarif_rule(rule_id: str) -> dict[str, object]:
+    descriptor = RULE_DESCRIPTORS[rule_id]
+    return {
+        "id": rule_id,
+        "shortDescription": {"text": descriptor["short"]},
+        "fullDescription": {"text": descriptor["full"]},
+        "helpUri": descriptor["help"],
+        "defaultConfiguration": {
+            "level": SEVERITY_TO_SARIF_LEVEL["high"],
+        },
+        "properties": {
+            "security-severity": SEVERITY_TO_SECURITY_SEVERITY["high"],
+        },
+    }
+
+
+def _sarif_result(finding: Finding, rule_index: int) -> dict[str, object]:
+    physical_location: dict[str, object] = {
+        "artifactLocation": {"uri": finding.file.replace("\\", "/")}
+    }
+    if finding.line is not None:
+        physical_location["region"] = {"startLine": finding.line}
+
+    return {
+        "ruleId": finding.rule_id,
+        "ruleIndex": rule_index,
+        "level": SEVERITY_TO_SARIF_LEVEL[finding.severity],
+        "message": {"text": finding.message},
+        "locations": [
+            {
+                "physicalLocation": physical_location,
+            }
+        ],
+        "partialFingerprints": {
+            "primaryLocationLineHash": _sarif_fingerprint(finding),
+        },
+        "properties": {
+            "severity": finding.severity,
+            "remediation": finding.remediation,
+        },
+    }
+
+
+def _sarif_fingerprint(finding: Finding) -> str:
+    source = "\0".join(
+        [
+            finding.rule_id,
+            finding.file.replace("\\", "/"),
+            "" if finding.line is None else str(finding.line),
+        ]
+    )
+    return hashlib.sha256(source.encode("utf-8")).hexdigest()

agentveil_posture/rules/__init__.py

@@ -0,0 +1,21 @@
+"""Rule registry stubs for AgentVeil Posture v0.1."""
+
+from __future__ import annotations
+
+from agentveil_posture.rules.identity import scan_identity_private_key_unencrypted
+from agentveil_posture.rules.manifest import is_agent_manifest, scan_manifest_rules
+from agentveil_posture.rules.workflow import scan_workflow_rules
+
+RULES = (
+    scan_identity_private_key_unencrypted,
+    scan_workflow_rules,
+    scan_manifest_rules,
+)
+
+__all__ = [
+    "RULES",
+    "is_agent_manifest",
+    "scan_identity_private_key_unencrypted",
+    "scan_manifest_rules",
+    "scan_workflow_rules",
+]

agentveil_posture/rules/identity.py

@@ -0,0 +1,51 @@
+"""Identity-related posture rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentveil_posture.report import Finding
+
+
+HEADER_LIMIT_BYTES = 4096
+PRIVATE_KEY_HEADERS = (
+    b"-----BEGIN PRIVATE KEY-----",
+    b"-----BEGIN RSA PRIVATE KEY-----",
+    b"-----BEGIN EC PRIVATE KEY-----",
+    b"-----BEGIN OPENSSH PRIVATE KEY-----",
+)
+ENCRYPTED_KEY_MARKERS = (
+    b"-----BEGIN ENCRYPTED PRIVATE KEY-----",
+    b"Proc-Type: 4,ENCRYPTED",
+)
+
+
+def scan_identity_private_key_unencrypted(root: Path, path: Path) -> Finding | None:
+    """Detect unencrypted private-key headers without exposing key material.
+
+    Legacy PEM encryption markers are expected in the bounded header window,
+    matching standard PEM output.
+    """
+    try:
+        with path.open("rb") as handle:
+            header = handle.read(HEADER_LIMIT_BYTES)
+    except OSError:
+        return None
+
+    if any(marker in header for marker in ENCRYPTED_KEY_MARKERS):
+        return None
+    if not any(header.startswith(marker) for marker in PRIVATE_KEY_HEADERS):
+        return None
+
+    return Finding(
+        rule_id="identity.private_key_unencrypted",
+        severity="high",
+        file=path.relative_to(root).as_posix(),
+        line=1,
+        message="Unencrypted private key file appears present.",
+        remediation=(
+            "Remove the key from the repository, rotate it if exposed, store it "
+            "in a secret manager, and use encrypted private key material when "
+            "local keys are unavoidable."
+        ),
+    )

agentveil_posture/rules/manifest.py

@@ -0,0 +1,166 @@
+"""Agent/tool manifest posture rules."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+import re
+from typing import Any
+
+from agentveil_posture.report import Finding
+from agentveil_posture.rules.parsing import ParsedDocument, load_json_document, load_yaml_document
+
+
+EXACT_MANIFEST_PATHS = {
+    ".mcp.json",
+    ".cursor/mcp.json",
+    "mcp.json",
+    "mcp_config.json",
+}
+MANIFEST_NAME_PATTERNS = (
+    "crew*.yaml",
+    "crew*.yml",
+    "autogen*.json",
+    "autogen*.yaml",
+    "autogen*.yml",
+    "langchain*.json",
+    "langchain*.yaml",
+    "langchain*.yml",
+)
+CREWAI_PATH_REGEX = re.compile(r"(^|/)crews/[^/]+/config/(agents|tasks)\.ya?ml$")
+DIRECT_GITHUB_TOKEN_RE = re.compile(
+    r"\bsecrets\.(GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT)\b"
+    r"|^\s*[\"']?(GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT|github-token)[\"']?\s*[:=]"
+    r"|[\"'](GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT|github-token)[\"']\s*:",
+    re.IGNORECASE | re.MULTILINE,
+)
+SHELL_KEY_RE = re.compile(r"(^|[_-])(shell|bash|command|terminal|subprocess)([_-]|$)", re.I)
+SHELL_LINE_RE = re.compile(
+    r"(^|[\s,{])[\"']?(shell|bash|command|terminal|subprocess)[\"']?\s*[:=]",
+    re.I,
+)
+APPROVAL_KEY_RE = re.compile(r"(approval|approve|human)", re.I)
+MAX_MANIFEST_SCAN_DEPTH = 100
+
+
+def is_agent_manifest(root: Path, path: Path) -> bool:
+    relative = path.relative_to(root).as_posix()
+    if relative in EXACT_MANIFEST_PATHS:
+        return True
+    if CREWAI_PATH_REGEX.search(relative):
+        return True
+    name = path.name.lower()
+    return any(fnmatch.fnmatch(name, pattern) for pattern in MANIFEST_NAME_PATTERNS)
+
+
+def scan_manifest_rules(root: Path, path: Path) -> list[Finding]:
+    document = load_manifest(path)
+    if document is None:
+        return []
+    findings: list[Finding] = []
+    findings.extend(scan_manifest_direct_github_token(root, path, document))
+    findings.extend(scan_manifest_shell_without_approval(root, path, document))
+    return findings
+
+
+def load_manifest(path: Path) -> ParsedDocument | None:
+    if path.suffix.lower() == ".json":
+        return load_json_document(path)
+    if path.suffix.lower() in {".yaml", ".yml"}:
+        return load_yaml_document(path)
+    return None
+
+
+def scan_manifest_direct_github_token(
+    root: Path, path: Path, document: ParsedDocument
+) -> list[Finding]:
+    line = _first_matching_line(document.lines, DIRECT_GITHUB_TOKEN_RE)
+    if line is None:
+        return []
+    return [
+        Finding(
+            rule_id="bypass.direct_github_token",
+            severity="high",
+            file=path.relative_to(root).as_posix(),
+            line=line,
+            message="Agent/tool manifest appears to expose direct GitHub token access.",
+            remediation=(
+                "Remove direct GitHub tokens from agent manifests, restrict token "
+                "permissions, and require approval for GitHub write or deploy paths."
+            ),
+        )
+    ]
+
+
+def scan_manifest_shell_without_approval(
+    root: Path, path: Path, document: ParsedDocument
+) -> list[Finding]:
+    try:
+        has_shell = _has_shell_capability(document.data)
+        has_approval = _has_approval_signal(document.data)
+    except RecursionError:
+        return []
+    if not has_shell or has_approval:
+        return []
+    return [
+        Finding(
+            rule_id="tool.shell_without_approval",
+            severity="high",
+            file=path.relative_to(root).as_posix(),
+            line=_first_shell_line(document.lines),
+            message="Agent/tool manifest appears to enable shell execution without approval.",
+            remediation=(
+                "Require explicit approval or a narrow allowlist before enabling "
+                "shell, terminal, command, bash, or subprocess tools."
+            ),
+        )
+    ]
+
+
+def _has_shell_capability(value: Any, depth: int = 0) -> bool:
+    if depth > MAX_MANIFEST_SCAN_DEPTH:
+        return False
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if SHELL_KEY_RE.search(str(key)) and _value_enabled(child):
+                return True
+            if _has_shell_capability(child, depth + 1):
+                return True
+    if isinstance(value, list):
+        return any(_has_shell_capability(item, depth + 1) for item in value)
+    return False
+
+
+def _has_approval_signal(value: Any, depth: int = 0) -> bool:
+    if depth > MAX_MANIFEST_SCAN_DEPTH:
+        return False
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if APPROVAL_KEY_RE.search(str(key)) and _value_enabled(child):
+                return True
+            if _has_approval_signal(child, depth + 1):
+                return True
+    if isinstance(value, list):
+        return any(_has_approval_signal(item, depth + 1) for item in value)
+    return False
+
+
+def _value_enabled(value: Any) -> bool:
+    if value is None or value is False:
+        return False
+    if isinstance(value, str):
+        return value.strip().lower() not in {"", "false", "no", "off", "none"}
+    if isinstance(value, (list, dict)):
+        return bool(value)
+    return True
+
+
+def _first_shell_line(lines: list[str]) -> int | None:
+    return _first_matching_line(lines, SHELL_LINE_RE)
+
+
+def _first_matching_line(lines: list[str], pattern: re.Pattern[str]) -> int | None:
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            return line_number
+    return None

agentveil_posture/rules/parsing.py

@@ -0,0 +1,72 @@
+"""Bounded parsers for untrusted scanned configuration files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+MAX_TEXT_BYTES = 1_000_000
+MAX_YAML_ALIAS_TOKENS = 25
+
+
+@dataclass(frozen=True)
+class ParsedDocument:
+    data: Any
+    text: str
+    lines: list[str]
+
+
+def load_yaml_document(path: Path, max_bytes: int = MAX_TEXT_BYTES) -> ParsedDocument | None:
+    text = read_bounded_text(path, max_bytes=max_bytes)
+    if text is None or has_excessive_yaml_aliases(text):
+        return None
+    try:
+        data = yaml.safe_load(text)
+    except (yaml.YAMLError, RecursionError):
+        return None
+    return ParsedDocument(data=data, text=text, lines=text.splitlines())
+
+
+def load_json_document(path: Path, max_bytes: int = MAX_TEXT_BYTES) -> ParsedDocument | None:
+    text = read_bounded_text(path, max_bytes=max_bytes)
+    if text is None:
+        return None
+    try:
+        data = json.loads(text)
+    except (json.JSONDecodeError, RecursionError):
+        return None
+    return ParsedDocument(data=data, text=text, lines=text.splitlines())
+
+
+def read_bounded_text(path: Path, max_bytes: int = MAX_TEXT_BYTES) -> str | None:
+    try:
+        if path.stat().st_size > max_bytes:
+            return None
+        return path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def has_excessive_yaml_aliases(text: str) -> bool:
+    aliases = 0
+    try:
+        for token in yaml.scan(text):
+            if isinstance(token, yaml.AliasToken):
+                aliases += 1
+                if aliases > MAX_YAML_ALIAS_TOKENS:
+                    return True
+    except yaml.YAMLError:
+        return True
+    return False
+
+
+def first_matching_line(lines: list[str], pattern) -> int | None:
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            return line_number
+    return None

agentveil_posture/rules/workflow.py

@@ -0,0 +1,182 @@
+"""GitHub workflow posture rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+from agentveil_posture.report import Finding
+from agentveil_posture.rules.parsing import (
+    MAX_TEXT_BYTES as MAX_WORKFLOW_BYTES,
+    MAX_YAML_ALIAS_TOKENS,
+    ParsedDocument,
+    load_yaml_document,
+)
+
+
+DEPLOY_MARKER_RE = re.compile(
+    r"\b(deploy|deployment|release|kubectl)\b"
+    r"|\b(npm|pnpm|yarn|pypi|twine|poetry)\s+publish\b"
+    r"|\bterraform\s+apply\b"
+    r"|\bcloudformation\s+deploy\b"
+    r"|\bserverless\s+deploy\b",
+    re.IGNORECASE,
+)
+BUILD_CONFIG_EXCLUSIONS = re.compile(
+    r"--configuration\s+\w+"
+    r"|--framework\s+\w+"
+    r"|\brelease\s+notes\b"
+    r"|\brelease\s+candidate\b",
+    re.IGNORECASE,
+)
+APPROVAL_MARKERS = ("approval", "manual approval", "review", "protected environment")
+PULL_REQUEST_TARGET_RE = re.compile(r"(^|\s)pull_request_target\s*:", re.MULTILINE)
+PULL_REQUEST_TARGET_INLINE_RE = re.compile(
+    r"^\s*on\s*:\s*(\[.*pull_request_target.*\]|pull_request_target)\s*$",
+    re.MULTILINE,
+)
+PULL_REQUEST_TARGET_LIST_RE = re.compile(r"^\s*-\s*pull_request_target\s*$", re.MULTILINE)
+DIRECT_GITHUB_TOKEN_RE = re.compile(
+    r"\bsecrets\.(GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT)\b"
+    r"|^\s*(GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT|github-token)\s*:",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def scan_workflow_rules(root: Path, path: Path) -> list[Finding]:
+    document = load_workflow(path)
+    if document is None:
+        return []
+    findings: list[Finding] = []
+    findings.extend(scan_workflow_direct_github_token(root, path, document))
+    findings.extend(scan_workflow_deploy_without_approval(root, path, document))
+    findings.extend(scan_workflow_pull_request_target_secrets_risk(root, path, document))
+    return findings
+
+
+def scan_workflow_direct_github_token(
+    root: Path, path: Path, document: ParsedDocument
+) -> list[Finding]:
+    line = _first_matching_line(document.lines, DIRECT_GITHUB_TOKEN_RE)
+    if line is None:
+        return []
+    return [
+        Finding(
+            rule_id="bypass.direct_github_token",
+            severity="high",
+            file=path.relative_to(root).as_posix(),
+            line=line,
+            message="Workflow appears to expose direct GitHub token access.",
+            remediation=(
+                "Restrict GitHub token permissions, avoid passing direct write "
+                "tokens to agent-controlled steps, and require approval for "
+                "GitHub write or deploy paths."
+            ),
+        )
+    ]
+
+
+def scan_workflow_deploy_without_approval(
+    root: Path, path: Path, document: ParsedDocument
+) -> list[Finding]:
+    deploy_line = _first_deploy_line(document.lines)
+    if deploy_line is None or _has_approval_signal(document.text):
+        return []
+    return [
+        Finding(
+            rule_id="workflow.deploy_without_approval",
+            severity="high",
+            file=path.relative_to(root).as_posix(),
+            line=deploy_line,
+            message="Deployment workflow appears to run without an approval gate.",
+            remediation=(
+                "Add a protected GitHub environment or explicit manual approval "
+                "before production deploy, release, or publish steps."
+            ),
+        )
+    ]
+
+
+def scan_workflow_pull_request_target_secrets_risk(
+    root: Path, path: Path, document: ParsedDocument
+) -> list[Finding]:
+    trigger_line = _pull_request_target_line(document.lines)
+    if trigger_line is None or not _has_pull_request_target_risk(document.text):
+        return []
+    return [
+        Finding(
+            rule_id="workflow.pull_request_target_secrets_risk",
+            severity="high",
+            file=path.relative_to(root).as_posix(),
+            line=trigger_line,
+            message=(
+                "pull_request_target workflow appears to combine privileged PR "
+                "context with checkout, shell execution, or secrets access."
+            ),
+            remediation=(
+                "Use pull_request for untrusted checks, avoid checking out fork "
+                "code in privileged workflows, and isolate any secret-bearing jobs."
+            ),
+        )
+    ]
+
+
+def load_workflow(path: Path) -> ParsedDocument | None:
+    return load_yaml_document(path, max_bytes=MAX_WORKFLOW_BYTES)
+
+
+def _first_deploy_line(lines: list[str]) -> int | None:
+    for line_number, line in enumerate(lines, start=1):
+        if BUILD_CONFIG_EXCLUSIONS.search(line):
+            continue
+        if DEPLOY_MARKER_RE.search(line):
+            return line_number
+    return None
+
+
+def _first_matching_line(lines: list[str], pattern: re.Pattern[str]) -> int | None:
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            return line_number
+    return None
+
+
+def _has_approval_signal(text: str) -> bool:
+    normalized = text.lower()
+    if re.search(r"^\s*environment\s*:", text, flags=re.MULTILINE):
+        return True
+    return any(marker in normalized for marker in APPROVAL_MARKERS)
+
+
+def _pull_request_target_line(lines: list[str]) -> int | None:
+    for line_number, line in enumerate(lines, start=1):
+        if line.lstrip().startswith("#"):
+            continue
+        if "pull_request_target" in line:
+            return line_number
+    return None
+
+
+def _has_pull_request_target_risk(text: str) -> bool:
+    if not _has_pull_request_target_trigger(text):
+        return False
+    normalized = text.lower()
+    return (
+        "actions/checkout" in normalized
+        or "${{ secrets." in normalized
+        or re.search(r"^\s*-?\s*run\s*:", text, flags=re.MULTILINE) is not None
+        or "github.event.pull_request.head" in normalized
+    )
+
+
+def _has_pull_request_target_trigger(text: str) -> bool:
+    text = _without_comment_lines(text)
+    return (
+        PULL_REQUEST_TARGET_RE.search(text) is not None
+        or PULL_REQUEST_TARGET_INLINE_RE.search(text) is not None
+        or PULL_REQUEST_TARGET_LIST_RE.search(text) is not None
+    )
+
+
+def _without_comment_lines(text: str) -> str:
+    return "\n".join(line for line in text.splitlines() if not line.lstrip().startswith("#"))

agentveil_posture/scanner.py

@@ -0,0 +1,61 @@
+"""Static scan orchestrator for AgentVeil Posture."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from agentveil_posture.report import Finding, PostureReport, build_report
+from agentveil_posture.rules import (
+    is_agent_manifest,
+    scan_identity_private_key_unencrypted,
+    scan_manifest_rules,
+    scan_workflow_rules,
+)
+
+
+class ScanError(Exception):
+    """Raised when the requested scan path cannot be scanned safely."""
+
+
+def scan_path(path: Path) -> PostureReport:
+    """Run a static, read-only scan for the currently implemented v0.1 rules."""
+    root = path.resolve()
+    if not root.exists():
+        raise ScanError(f"scan path does not exist: {path}")
+    if not root.is_dir():
+        raise ScanError(f"scan path is not a directory: {path}")
+
+    findings: list[Finding] = []
+    for candidate in _iter_regular_files(root):
+        finding = scan_identity_private_key_unencrypted(root, candidate)
+        if finding is not None:
+            findings.append(finding)
+        if _is_github_workflow(root, candidate):
+            findings.extend(scan_workflow_rules(root, candidate))
+        if is_agent_manifest(root, candidate):
+            findings.extend(scan_manifest_rules(root, candidate))
+
+    return build_report(str(root), findings)
+
+
+def _iter_regular_files(root: Path) -> list[Path]:
+    paths: list[Path] = []
+    for dirpath, _dirnames, filenames in os.walk(str(root), followlinks=False):
+        for filename in filenames:
+            path = Path(dirpath) / filename
+            if path.is_symlink():
+                continue
+            if path.is_file():
+                paths.append(path)
+    return sorted(paths)
+
+
+def _is_github_workflow(root: Path, path: Path) -> bool:
+    relative = path.relative_to(root)
+    return (
+        len(relative.parts) >= 3
+        and relative.parts[0] == ".github"
+        and relative.parts[1] == "workflows"
+        and path.suffix.lower() in {".yml", ".yaml"}
+    )

agentveil_posture-0.1.0.dist-info/METADATA

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: agentveil-posture
+Version: 0.1.0
+Summary: Pre-deployment posture checks for risky AI agent capabilities.
+Author: AgentVeil Protocol contributors
+License-Expression: MIT
+Project-URL: Homepage, https://agentveil.dev
+Project-URL: Repository, https://github.com/agentveil-protocol/agentveil-posture
+Project-URL: Issues, https://github.com/agentveil-protocol/agentveil-posture/issues
+Project-URL: Documentation, https://github.com/agentveil-protocol/agentveil-posture#readme
+Keywords: security,agent,mcp,posture,github-actions,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# AgentVeil Posture
+
+<p align="center">
+  <img src="docs/agentveil-posture-logo.png" alt="AgentVeil Posture logo" width="180">
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/agentveil-posture?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/agentveil-posture/)
+[![Self Test](https://github.com/agentveil-protocol/agentveil-posture/actions/workflows/posture-self-test.yml/badge.svg)](https://github.com/agentveil-protocol/agentveil-posture/actions/workflows/posture-self-test.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![GitHub stars](https://img.shields.io/github/stars/agentveil-protocol/agentveil-posture?style=for-the-badge&logo=github&color=gold)](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
+[![GitHub Action](https://img.shields.io/badge/GitHub-Action_ready-2088FF?style=for-the-badge&logo=github-actions&logoColor=white)](#use-as-a-github-action)
+[![Posture: read-only](https://img.shields.io/badge/scanner-read--only-10b981?style=for-the-badge)](#hard-constraints)
+
+**Pre-deployment posture check for AI agents. Find risky capabilities before they become production incidents.**
+
+`agentveil-posture` is a pre-deployment, static, local-only scanner that flags
+risky AI-agent and GitHub-workflow posture issues. No telemetry, no network
+calls, no project code execution. v0.1 ships five high-severity GitHub-focused
+rules.
+
+[Quick Start](#quick-start) |
+[What a finding looks like](#what-a-finding-looks-like) |
+[Detection scope](#detection-scope-v01) |
+[GitHub Action](#use-as-a-github-action) |
+[Why this exists](#why-this-exists)
+
+---
+
+## Quick Start
+
+```bash
+pip install agentveil-posture
+agentveil posture scan --path . --output report.json
+cat report.json
+```
+
+That is the whole flow. The scanner is read-only: it does not modify your
+files, run your code, or send data over the network.
+
+To fail CI when findings meet a threshold, add `--fail-on`:
+
+```bash
+agentveil posture scan --path . --output report.json --fail-on high
+```
+
+## What a Finding Looks Like
+
+```json
+{
+  "rule_id": "workflow.deploy_without_approval",
+  "severity": "high",
+  "file": ".github/workflows/deploy.yml",
+  "line": 12,
+  "message": "Deployment workflow appears to run without an approval gate.",
+  "remediation": "Add a protected GitHub environment or explicit manual approval before production deploy, release, or publish steps."
+}
+```
+
+Every finding contains rule ID, severity, repository-relative file path, line
+number when available, redacted message, and remediation pointer. Raw secrets,
+command bodies, and key material never appear in the report.
+
+## Detection Scope (v0.1)
+
+All v0.1 rules are reported as `high` severity.
+
+| Rule | What it flags |
+|---|---|
+| `bypass.direct_github_token` | Direct GitHub PAT/token references in workflows or agent manifests |
+| `workflow.deploy_without_approval` | Deploy/release/publish steps without an approval gate |
+| `workflow.pull_request_target_secrets_risk` | `pull_request_target` workflows that combine privileged context with checkout, run, or secrets |
+| `tool.shell_without_approval` | Agent tool manifests that enable shell execution without an approval flag |
+| `identity.private_key_unencrypted` | Unencrypted PEM private key files committed to the repo |
+
+## Install
+
+<details>
+<summary><b>From PyPI (recommended)</b></summary>
+
+```bash
+pip install agentveil-posture
+```
+
+</details>
+
+<details>
+<summary><b>From GitHub release</b></summary>
+
+```bash
+pip install git+https://github.com/agentveil-protocol/agentveil-posture@v0.1.0
+```
+
+</details>
+
+<details>
+<summary><b>From source (development)</b></summary>
+
+```bash
+git clone https://github.com/agentveil-protocol/agentveil-posture
+cd agentveil-posture
+pip install -e .
+```
+
+</details>
+
+## Use as a GitHub Action
+
+Use the action from the same repository:
+
+```yaml
+- uses: agentveil-protocol/agentveil-posture@v0.1.0
+  with:
+    path: "."
+    output: agentveil-posture-report.json
+    fail-on: high
+```
+
+The action requires Python 3.10 or newer on the runner. It writes the report
+path to the `report` output and does not upload data to AgentVeil. Omit
+`fail-on` to keep review-only behavior.
+
+For GitHub Code Scanning, write SARIF and upload it with CodeQL:
+
+```yaml
+- uses: agentveil-protocol/agentveil-posture@v0.1.0
+  with:
+    path: "."
+    output: agentveil-posture.sarif
+    format: sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: agentveil-posture.sarif
+```
+
+## Pre-commit Hook
+
+Run AgentVeil Posture as a [pre-commit](https://pre-commit.com) hook to catch
+posture issues before they reach the remote.
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/agentveil-protocol/agentveil-posture
+    rev: v0.1.0
+    hooks:
+      - id: agentveil-posture
+        args: ["--fail-on", "high"]
+```
+
+Then install:
+
+```bash
+pre-commit install
+```
+
+The hook generates `agentveil-posture-report.json` on every commit. Omit
+`args` for review-only behavior, or use `--fail-on` to block commits when
+findings meet the selected threshold.
+
+## Triaging Findings
+
+`agentveil-posture` flags **posture surfaces**: places where an AI agent or
+workflow has direct capability to do something risky. Most findings are
+**review items**, not incidents:
+
+- **`bypass.direct_github_token`** commonly appears on stale-bots,
+  release-bots, CI publish steps, and label-management workflows that
+  legitimately use the auto-injected `secrets.GITHUB_TOKEN`. The rule fires
+  by design: the workflow holds direct GitHub write capability and that is a
+  posture surface worth surfacing, even when expected.
+- **`workflow.deploy_without_approval`** may flag deploy paths that have
+  approval mechanisms the static scanner cannot see, such as manual job
+  dispatch, branch protection, or external reviewer chains. Verify against
+  your actual approval flow before treating as incident.
+- **`workflow.pull_request_target_secrets_risk`** flags risky combinations,
+  but some `pull_request_target` workflows are correctly scoped to label-only
+  or metadata-only operations. Re-check the actual job content.
+- **`tool.shell_without_approval`** flags inline shell capability
+  declarations. Tools referenced by name, such as `search_tool` in CrewAI,
+  are not detected; only literal `shell:` or `bash:` keys are.
+- **`identity.private_key_unencrypted`** is the most reliably actionable
+  finding: committed unencrypted private keys are usually real issues.
+
+Use posture-check to surface review items for human triage, not to auto-block
+CI or replace SAST/secret-scanning tools.
+
+## Why This Exists
+
+AI agents increasingly touch production credentials, deploy workflows, and
+developer infrastructure. AgentVeil Posture is the first step: find risky
+capabilities before deployment and before they become incidents.
+
+```text
+  +----------+      +----------+      +----------+
+  |   FIND   |      |  DECIDE  |      |  PROVE   |
+  |  risky   | ---> |  what is | ---> |  what    |
+  |   caps   |      |  allowed |      | happened |
+  +----------+      +----------+      +----------+
+   you are here       roadmap          roadmap
+   v0.1 Posture
+```
+
+| | Posture does | Posture does not |
+|---|---|---|
+| Scope | Static analysis and posture risk patterns | Approval, blocking, or execution of agent actions |
+| Effects | Read-only file inspection | Code execution, network calls, or file mutation |
+| Output | Redacted JSON findings | Secret values, command bodies, or key bytes |
+
+For the broader AgentVeil project, see [agentveil.dev](https://agentveil.dev).
+
+## Hard Constraints
+
+The scanner is designed to be:
+
+- **offline**: no network calls
+- **telemetry-free**: no usage data collected
+- **read-only**: does not modify scanned files
+- **static-only**: does not execute scanned project code
+- **secret-safe**: reports only redacted findings
+
+Private-key checks use file metadata and bounded header sniffing only.
+
+## Dependency Policy
+
+Runtime dependencies are intentionally minimal:
+
+- Python `>=3.10`
+- `PyYAML>=6.0.1,<7`
+
+Additional runtime dependencies require explicit justification in
+[PLAN.md](PLAN.md).
+
+## Known Limitations
+
+`agentveil-posture` v0.1 is a best-effort heuristic scanner, not an exhaustive
+security audit.
+
+- Some rules may produce false positives or false negatives.
+- Oversized, unreadable, or malformed inputs may be skipped without per-file
+  skip reasons.
+- YAML parsing is bounded, but carefully crafted YAML within the v0.1 alias
+  limit can still consume parser memory.
+- The repository includes an intentional synthetic PEM-shaped fixture for
+  scanner tests. It is not a real private key.
+
+## Community
+
+- [Star this repo](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
+  if Posture helps your team.
+- [Open an issue](https://github.com/agentveil-protocol/agentveil-posture/issues)
+  for bugs, false positives, or rule suggestions.
+- See [PLAN.md](PLAN.md) for the v0.1 spec, schema details, and v0.2 backlog.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Part of the [AgentVeil project](https://agentveil.dev): action control for
+autonomous agents.

agentveil_posture-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agentveil_posture/__init__.py,sha256=Dgw7FEUaYoFV0C4WHG2n5w5SYQoIIbIOiA8a-zFsABI,91
+agentveil_posture/cli.py,sha256=kWraymEt1oCQXPSs63nbl_cXcTfEnn8wxSfjcthxwB4,2883
+agentveil_posture/report.py,sha256=O6WX-aCQsPbQs_XWxLzELe9VW6IsLNRUuQl_03NWDsE,7032
+agentveil_posture/scanner.py,sha256=v4zhZAHi-f-ChtUeaTn8l37bd2etIvB74FUQdU-arlc,1967
+agentveil_posture/rules/__init__.py,sha256=hXCYfGaAhdYVAjj1MmSD5EG8gRssRiftQmGv9bGqTNQ,581
+agentveil_posture/rules/identity.py,sha256=Ja--Wi0pYpUkU-itZhA1LWZxqfRUKsOF2CFsnHrzJYo,1544
+agentveil_posture/rules/manifest.py,sha256=ntzVosGBk4NHuhcrlSlFBhsGiqiW6F8Ug4dU1_dYoBc,5441
+agentveil_posture/rules/parsing.py,sha256=JjJMCpuZOpQlc17zDjdn3t2EaliZT2CQlF-PE0O2jl8,1975
+agentveil_posture/rules/workflow.py,sha256=D_XcjNPtC2d8ytRPlQoC94naAA7Sm9LOJV5MbcF056c,6165
+agentveil_posture-0.1.0.dist-info/licenses/LICENSE,sha256=tINj2Q4xPZbm90mBF98TA4FWxlpmvcKGrOh8vLF0f64,1088
+agentveil_posture-0.1.0.dist-info/METADATA,sha256=ihh3rHGupC_xRHDvNubSRPbqPVVdni7rZWT9pXXDgQ8,10515
+agentveil_posture-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentveil_posture-0.1.0.dist-info/entry_points.txt,sha256=n7anDKPyXHTY6khIeNX3v53bu5BvcNAVaa7VCUxv4hA,57
+agentveil_posture-0.1.0.dist-info/top_level.txt,sha256=O9TZzoSTHqDrSDHjG9za84UBuqgDfOoIpPrPpUoGras,18
+agentveil_posture-0.1.0.dist-info/RECORD,,

agentveil_posture-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentveil_posture-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentveil = agentveil_posture.cli:main

agentveil_posture-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentVeil Protocol contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentveil_posture-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentveil_posture