agentsentinel-cli 0.3.0__py3-none-any.whl

agentsentinel_cli/rules.py

@@ -0,0 +1,239 @@
+"""Standalone posture rules — no database required, works purely on static analysis."""
+
+import dataclasses
+from agentsentinel_cli.scanner import AgentInfo, ToolInfo
+
+
+@dataclasses.dataclass
+class Finding:
+    severity: str       # CRITICAL | HIGH | MEDIUM | LOW
+    rule_id: str
+    message: str
+    detail: str = ""
+
+
+_INTERNAL_READ_KW = {"db", "database", "crm", "file", "filesystem", "s3_read", "storage_read", "read_file"}
+_EXTERNAL_WRITE_KW = {"email", "smtp", "webhook", "http_post", "http_external", "s3_write", "send", "slack"}
+_READ_PURPOSE_WORDS = {"read", "search", "query", "view", "lookup", "fetch", "get", "retrieve"}
+_CODE_EXEC_CATEGORIES = {"code_execution"}
+_SECRETS_CATEGORIES = {"secrets"}
+_ADMIN_CATEGORIES = {"admin"}
+_INFRA_CATEGORIES = {"infrastructure"}
+_WEB_CATEGORIES = {"web"}
+
+
+def _rule_exfiltration_path(agent: AgentInfo) -> Finding | None:
+    tool_names = {t.name.lower() for t in agent.tools}
+    internal_hits = [n for n in tool_names if any(kw in n for kw in _INTERNAL_READ_KW)]
+    external_hits = [n for n in tool_names if any(kw in n for kw in _EXTERNAL_WRITE_KW)]
+    if internal_hits and external_hits:
+        return Finding(
+            severity="CRITICAL",
+            rule_id="EXFILTRATION_PATH",
+            message="Agent holds both internal-read and external-write grants.",
+            detail=f"Internal-read: {', '.join(internal_hits)} | External-write: {', '.join(external_hits)}",
+        )
+    return None
+
+
+def _rule_code_execution_grant(agent: AgentInfo) -> Finding | None:
+    """CRITICAL: agent holds code execution tools — arbitrary code paths are high-risk."""
+    exec_tools = [t.name for t in agent.tools if t.category in _CODE_EXEC_CATEGORIES]
+    if exec_tools:
+        return Finding(
+            severity="CRITICAL",
+            rule_id="CODE_EXECUTION_GRANT",
+            message="Agent holds code-execution grants. Arbitrary code execution enables full host compromise.",
+            detail=f"Execution tools: {', '.join(exec_tools)}",
+        )
+    return None
+
+
+def _rule_hardcoded_credentials(agent: AgentInfo) -> Finding | None:
+    """CRITICAL: hardcoded API keys or secrets detected in source code."""
+    if agent.hardcoded_creds:
+        return Finding(
+            severity="CRITICAL",
+            rule_id="HARDCODED_CREDENTIALS",
+            message="Hardcoded credentials detected. Rotate immediately and move to environment variables.",
+            detail="; ".join(agent.hardcoded_creds),
+        )
+    return None
+
+
+def _rule_secrets_access_grant(agent: AgentInfo) -> Finding | None:
+    """HIGH: agent has tools that read secrets, vaults, or credentials at runtime."""
+    secrets_tools = [t.name for t in agent.tools if t.category in _SECRETS_CATEGORIES]
+    if secrets_tools:
+        return Finding(
+            severity="HIGH",
+            rule_id="SECRETS_ACCESS_GRANT",
+            message="Agent holds secrets-access grants. Verify this agent needs runtime access to credentials.",
+            detail=f"Secrets tools: {', '.join(secrets_tools)}",
+        )
+    return None
+
+
+def _rule_prompt_injection_vector(agent: AgentInfo) -> Finding | None:
+    """HIGH: agent reads from untrusted web sources AND holds write grants — injection-to-write path."""
+    has_web_read = any(t.category in _WEB_CATEGORIES for t in agent.tools)
+    write_tools = [t.name for t in agent.tools if t.scope == "write"]
+    if has_web_read and write_tools:
+        return Finding(
+            severity="HIGH",
+            rule_id="PROMPT_INJECTION_VECTOR",
+            message=(
+                "Agent reads from web (untrusted input) and holds write grants — "
+                "prompt injection could redirect write operations."
+            ),
+            detail=f"Write grants: {', '.join(write_tools)}",
+        )
+    return None
+
+
+def _rule_lateral_movement_path(agent: AgentInfo) -> Finding | None:
+    """HIGH: agent combines admin/IAM grants with network or infrastructure tools."""
+    admin_tools = [t.name for t in agent.tools if t.category in _ADMIN_CATEGORIES]
+    infra_tools = [t.name for t in agent.tools if t.category in _INFRA_CATEGORIES]
+    if admin_tools and infra_tools:
+        return Finding(
+            severity="HIGH",
+            rule_id="LATERAL_MOVEMENT_PATH",
+            message=(
+                "Agent holds admin/IAM grants alongside infrastructure grants — "
+                "potential lateral movement via privilege escalation."
+            ),
+            detail=f"Admin: {', '.join(admin_tools)} | Infra: {', '.join(infra_tools)}",
+        )
+    return None
+
+
+def _rule_unbounded_file_access(agent: AgentInfo) -> Finding | None:
+    """HIGH: agent holds filesystem write grants with no description restricting scope."""
+    fs_write = [
+        t.name for t in agent.tools
+        if t.category == "filesystem" and t.scope == "write"
+    ]
+    if fs_write and not agent.description:
+        return Finding(
+            severity="HIGH",
+            rule_id="UNBOUNDED_FILE_ACCESS",
+            message=(
+                "Agent holds filesystem write grants with no description. "
+                "Without scoped intent, write access is effectively unbounded."
+            ),
+            detail=f"Filesystem write tools: {', '.join(fs_write)}",
+        )
+    return None
+
+
+def _rule_privilege_excess(agent: AgentInfo) -> Finding | None:
+    if not agent.description:
+        return None
+    desc = agent.description.lower()
+    if not any(w in desc for w in _READ_PURPOSE_WORDS):
+        return None
+    elevated = [t.name for t in agent.tools if t.scope in ("write",) or t.is_dangerous]
+    if elevated:
+        return Finding(
+            severity="HIGH",
+            rule_id="PRIVILEGE_EXCESS",
+            message="Agent description implies read-only purpose but holds write/dangerous grants.",
+            detail=f"Elevated grants: {', '.join(elevated)}",
+        )
+    return None
+
+
+def _rule_dangerous_grants(agent: AgentInfo) -> Finding | None:
+    dangerous = [t.name for t in agent.tools if t.is_dangerous]
+    if dangerous:
+        return Finding(
+            severity="HIGH",
+            rule_id="DANGEROUS_GRANTS",
+            message="Agent holds dangerous tool grants. Verify intent and add rate limits.",
+            detail=f"Dangerous tools: {', '.join(dangerous)}",
+        )
+    return None
+
+
+def _rule_tool_sprawl(agent: AgentInfo) -> Finding | None:
+    """MEDIUM: agent holds too many tools across too many categories — blast radius scales with sprawl."""
+    categories = {t.category for t in agent.tools if t.category != "other"}
+    if len(agent.tools) > 10 or len(categories) >= 5:
+        return Finding(
+            severity="MEDIUM",
+            rule_id="TOOL_SPRAWL",
+            message=(
+                f"Agent holds {len(agent.tools)} tools across {len(categories)} categories. "
+                "Reduce grants to the minimum required for each task."
+            ),
+            detail=f"Categories present: {', '.join(sorted(categories))}",
+        )
+    return None
+
+
+def _rule_write_without_description(agent: AgentInfo) -> Finding | None:
+    write_tools = [t.name for t in agent.tools if t.scope == "write"]
+    if write_tools and not agent.description:
+        return Finding(
+            severity="MEDIUM",
+            rule_id="UNDESCRIBED_WRITE_AGENT",
+            message="Agent has write-scope grants but no description.",
+            detail=(
+                f"Write tools: {', '.join(write_tools)}. "
+                "Add a description so posture rules can assess intent."
+            ),
+        )
+    return None
+
+
+def _rule_missing_rate_limit(agent: AgentInfo) -> Finding | None:
+    """Flag dangerous tools — rate limits aren't visible in static analysis."""
+    dangerous = [t.name for t in agent.tools if t.is_dangerous]
+    if dangerous:
+        return Finding(
+            severity="LOW",
+            rule_id="MISSING_RATE_LIMIT",
+            message="Dangerous grants detected. Ensure rate limits are configured at runtime.",
+            detail=f"Tools to check: {', '.join(dangerous)}",
+        )
+    return None
+
+
+_ALL_RULES = [
+    # CRITICAL
+    _rule_exfiltration_path,
+    _rule_code_execution_grant,
+    _rule_hardcoded_credentials,
+    # HIGH
+    _rule_secrets_access_grant,
+    _rule_prompt_injection_vector,
+    _rule_lateral_movement_path,
+    _rule_unbounded_file_access,
+    _rule_privilege_excess,
+    _rule_dangerous_grants,
+    # MEDIUM
+    _rule_tool_sprawl,
+    _rule_write_without_description,
+    # LOW
+    _rule_missing_rate_limit,
+]
+
+_SEVERITY_WEIGHT = {"CRITICAL": 40, "HIGH": 20, "MEDIUM": 10, "LOW": 5}
+
+
+def run_rules(agent: AgentInfo) -> list[Finding]:
+    findings = []
+    seen_rules: set[str] = set()
+    for rule_fn in _ALL_RULES:
+        f = rule_fn(agent)
+        if f and f.rule_id not in seen_rules:
+            findings.append(f)
+            seen_rules.add(f.rule_id)
+    return findings
+
+
+def posture_score(findings: list[Finding]) -> int:
+    """Calculate posture score (0-100) from findings, same formula as the platform."""
+    deductions = sum(_SEVERITY_WEIGHT.get(f.severity, 0) for f in findings)
+    return max(0, 100 - deductions)

agentsentinel_cli/scanner.py

@@ -0,0 +1,314 @@
+"""Static analysis engine — extracts tool definitions from Python agent files using AST."""
+
+import ast
+import dataclasses
+import re
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class ToolInfo:
+    name: str
+    scope: str          # "read" | "write"
+    is_dangerous: bool
+    source: str         # how it was detected
+    docstring: str = ""
+    category: str = "other"
+
+
+@dataclasses.dataclass
+class AgentInfo:
+    file: Path
+    tools: list[ToolInfo]
+    description: str = ""
+    model: str = ""
+    hardcoded_creds: list[str] = dataclasses.field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Classification helpers
+# ---------------------------------------------------------------------------
+
+_WRITE_PATTERNS = (
+    "write", "edit", "create", "delete", "remove", "move", "rename",
+    "execute", "run", "exec", "patch", "update", "insert", "drop",
+    "truncate", "send", "post", "put", "upload", "deploy", "reset", "kill",
+)
+_DANGEROUS_PATTERNS = (
+    "delete", "remove", "drop", "truncate", "execute", "run", "exec",
+    "send", "deploy", "reset", "kill",
+)
+_KNOWN_MODELS = (
+    "gpt-", "claude-", "gemini-", "mistral", "llama", "mixtral",
+    "command", "titan", "nova",
+)
+_TOOL_CATEGORIES = {
+    "database":      ("database", "db", "sql", "query", "postgres", "mysql", "mongo"),
+    "filesystem":    ("file", "directory", "disk", "path", "read_file", "write_file"),
+    "web":           ("http", "fetch", "url", "web", "scrape", "browse", "request"),
+    "communication": ("email", "smtp", "slack", "webhook", "notify", "send_message"),
+    "code_execution":("exec", "bash", "shell", "run_code", "eval", "terminal", "subprocess", "python_repl"),
+    "secrets":       ("secret", "credential", "vault", "token", "password", "api_key", "read_env"),
+    "admin":         ("admin", "iam", "role", "permission", "policy", "sudo", "privilege"),
+    "crm":           ("crm", "customer", "account", "contact", "salesforce", "hubspot"),
+    "analytics":     ("analytics", "metric", "report", "dashboard", "bi", "insight"),
+    "infrastructure":("deploy", "container", "k8s", "kubernetes", "aws", "gcp", "azure", "terraform"),
+}
+
+# Credential detection
+_CRED_VARNAMES = frozenset({
+    "api_key", "apikey", "api_token", "token", "secret", "password",
+    "passwd", "credential", "auth_token", "access_token", "secret_key",
+    "private_key", "bearer_token", "auth_key",
+})
+_CRED_PREFIXES = (
+    "sk-ant-", "sk-proj-", "sk-", "Bearer ", "ghp_", "gho_", "github_pat_",
+    "xoxb-", "xoxp-", "AIza", "ya29.", "AKIA", "eyJ",  # JWT
+)
+_CRED_REGEX = re.compile(r'^[A-Za-z0-9+/\-_]{32,}={0,2}$')
+
+
+def _classify(name: str) -> tuple[str, bool]:
+    lower = name.lower()
+    is_dangerous = any(p in lower for p in _DANGEROUS_PATTERNS)
+    is_write = is_dangerous or any(p in lower for p in _WRITE_PATTERNS)
+    return ("write" if is_write else "read"), is_dangerous
+
+
+def _categorize(name: str) -> str:
+    lower = name.lower()
+    for category, patterns in _TOOL_CATEGORIES.items():
+        if any(p in lower for p in patterns):
+            return category
+    return "other"
+
+
+def _get_string(node: ast.expr | None) -> str:
+    if node is None:
+        return ""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return ""
+
+
+def _looks_like_credential(value: str) -> bool:
+    if any(value.startswith(p) for p in _CRED_PREFIXES):
+        return len(value) > 16
+    return bool(_CRED_REGEX.match(value)) and len(value) >= 32
+
+
+def _has_decorator(
+    func_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    names: tuple[str, ...],
+) -> bool:
+    for dec in func_node.decorator_list:
+        if isinstance(dec, ast.Name) and dec.id in names:
+            return True
+        if isinstance(dec, ast.Attribute) and dec.attr in names:
+            return True
+        if isinstance(dec, ast.Call):
+            if isinstance(dec.func, ast.Name) and dec.func.id in names:
+                return True
+            if isinstance(dec.func, ast.Attribute) and dec.func.attr in names:
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# AST visitor
+# ---------------------------------------------------------------------------
+
+class _AgentFileVisitor(ast.NodeVisitor):
+    """Walk an AST and collect tool definitions, agent metadata, and credentials."""
+
+    def __init__(self) -> None:
+        self.tools: list[ToolInfo] = []
+        self.description: str = ""
+        self.model: str = ""
+        self.hardcoded_creds: list[str] = []
+        self._seen: set[str] = set()
+
+    def _add_tool(self, name: str, source: str, docstring: str = "") -> None:
+        if name in self._seen:
+            return
+        self._seen.add(name)
+        scope, is_dangerous = _classify(name)
+        self.tools.append(ToolInfo(
+            name=name,
+            scope=scope,
+            is_dangerous=is_dangerous,
+            source=source,
+            docstring=docstring,
+            category=_categorize(name),
+        ))
+
+    # ------------------------------------------------------------------
+    # @tool / @SentinelTool decorated functions
+    # ------------------------------------------------------------------
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        if _has_decorator(node, ("tool", "SentinelTool", "beta_tool", "betaZodTool")):
+            doc = ast.get_docstring(node) or ""
+            self._add_tool(node.name, "@tool decorator", doc)
+        self.generic_visit(node)
+
+    visit_AsyncFunctionDef = visit_FunctionDef
+
+    # ------------------------------------------------------------------
+    # Class-based tools
+    # ------------------------------------------------------------------
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        base_names = {
+            b.id if isinstance(b, ast.Name) else
+            (b.attr if isinstance(b, ast.Attribute) else "")
+            for b in node.bases
+        }
+        if "BaseTool" in base_names or "StructuredTool" in base_names:
+            for item in node.body:
+                if (
+                    isinstance(item, ast.Assign)
+                    and any(isinstance(t, ast.Name) and t.id == "name" for t in item.targets)
+                ):
+                    tool_name = _get_string(item.value)
+                    if tool_name:
+                        doc = ast.get_docstring(node) or ""
+                        self._add_tool(tool_name, "BaseTool subclass", doc)
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Tool() / StructuredTool() call-based tools + model + description
+    # ------------------------------------------------------------------
+
+    def visit_Call(self, node: ast.Call) -> None:
+        func_name = ""
+        if isinstance(node.func, ast.Name):
+            func_name = node.func.id
+        elif isinstance(node.func, ast.Attribute):
+            func_name = node.func.attr
+
+        if func_name in ("Tool", "StructuredTool"):
+            for kw in node.keywords:
+                if kw.arg == "name":
+                    tool_name = _get_string(kw.value)
+                    if tool_name:
+                        self._add_tool(tool_name, f"{func_name}(name=...)")
+
+        if func_name in ("ChatAnthropic", "ChatOpenAI", "ChatGoogleGenerativeAI",
+                         "AzureChatOpenAI", "BedrockChat", "init_chat_model"):
+            for kw in node.keywords:
+                if kw.arg == "model":
+                    val = _get_string(kw.value)
+                    if val and not self.model:
+                        self.model = val
+            if node.args:
+                val = _get_string(node.args[0])
+                if val and any(val.startswith(p) for p in _KNOWN_MODELS) and not self.model:
+                    self.model = val
+
+        if func_name == "create_agent" and node.args:
+            val = _get_string(node.args[0])
+            if val and not self.model:
+                self.model = val
+
+        if func_name == "SentinelCallbackHandler":
+            for kw in node.keywords:
+                if kw.arg == "description" and not self.description:
+                    self.description = _get_string(kw.value)
+
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Variable assignments — description detection + hardcoded credentials
+    # ------------------------------------------------------------------
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        for target in node.targets:
+            if not isinstance(target, ast.Name):
+                continue
+            varname = target.id.lower()
+
+            if "description" in varname and not self.description:
+                val = _get_string(node.value)
+                if val:
+                    self.description = val
+
+            # Credential detection: api_key = "sk-ant-..."
+            if varname in _CRED_VARNAMES:
+                val = _get_string(node.value)
+                if val and _looks_like_credential(val):
+                    self.hardcoded_creds.append(
+                        f"{target.id} = \"{val[:8]}…\" (line {node.lineno})"
+                    )
+
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Keyword arguments — catch api_key="..." in function calls
+    # ------------------------------------------------------------------
+
+    def visit_keyword(self, node: ast.keyword) -> None:
+        if node.arg and node.arg.lower() in _CRED_VARNAMES:
+            val = _get_string(node.value)
+            if val and _looks_like_credential(val):
+                self.hardcoded_creds.append(
+                    f"{node.arg} = \"{val[:8]}…\" (line {node.value.lineno})"  # type: ignore[attr-defined]
+                )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def scan_file(path: Path) -> AgentInfo | None:
+    """Parse a Python file and extract agent/tool information. Returns None on parse error."""
+    try:
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(path))
+    except (SyntaxError, OSError):
+        return None
+
+    visitor = _AgentFileVisitor()
+    visitor.visit(tree)
+
+    if not visitor.tools:
+        return None
+
+    return AgentInfo(
+        file=path,
+        tools=visitor.tools,
+        description=visitor.description,
+        model=visitor.model,
+        hardcoded_creds=visitor.hardcoded_creds,
+    )
+
+
+def classify_tool(name: str, description: str = "") -> tuple[str, bool, str]:
+    """Classify a tool by name and description into (scope, is_dangerous, category).
+
+    Used by both the static file scanner and the MCP scanner.
+    """
+    combined = f"{name} {description}".strip()
+    scope, is_dangerous = _classify(combined)
+    category = _categorize(combined)
+    return scope, is_dangerous, category
+
+
+def scan_path(target: Path) -> list[AgentInfo]:
+    """Scan a file or directory, returning one AgentInfo per file that contains tools."""
+    if target.is_file():
+        result = scan_file(target)
+        return [result] if result else []
+
+    results = []
+    for py_file in sorted(target.rglob("*.py")):
+        if any(part.startswith((".venv", "venv", "__pycache__", ".git", "node_modules"))
+               for part in py_file.parts):
+            continue
+        result = scan_file(py_file)
+        if result:
+            results.append(result)
+    return results