argus-appsec 0.1.0__py3-none-any.whl

argus/__init__.py

@@ -0,0 +1,28 @@
+"""Argus — an open-source AI Security Engineer.
+
+Argus maps an application, runs layered security analysis, explains each finding
+in terms a developer can act on, and — where possible — proposes and verifies a fix.
+"""
+
+from argus.core.models import (
+    Confidence,
+    Finding,
+    Location,
+    Remediation,
+    ScanResult,
+    Severity,
+)
+from argus.core.project import Project
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Confidence",
+    "Finding",
+    "Location",
+    "Project",
+    "Remediation",
+    "ScanResult",
+    "Severity",
+    "__version__",
+]

argus/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m argus``."""
+
+from argus.cli.main import app
+
+if __name__ == "__main__":
+    app()

argus/agents/__init__.py

@@ -0,0 +1,21 @@
+"""Specialized agents.
+
+Argus splits the "AI Security Engineer" role into focused agents, each with one
+job. They operate on findings after scanning: enriching the narrative, simulating
+attacks, and proposing fixes. Every agent degrades gracefully — with the
+heuristic provider it uses templated reasoning; with a real model it produces
+richer, context-aware analysis.
+"""
+
+from argus.agents.base import Agent, AgentContext
+from argus.agents.enrichment import EnrichmentAgent
+from argus.agents.exploit import AttackSimulationAgent
+from argus.agents.patch import PatchAgent
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AttackSimulationAgent",
+    "EnrichmentAgent",
+    "PatchAgent",
+]

argus/agents/base.py

@@ -0,0 +1,37 @@
+"""Agent base class and shared context."""
+
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass
+
+from argus.ai.base import AIProvider
+from argus.core.config import Config
+from argus.core.models import Finding
+from argus.core.project import Project
+
+
+@dataclass
+class AgentContext:
+    project: Project
+    config: Config
+    ai: AIProvider
+
+
+class Agent(abc.ABC):
+    """Base class for finding-processing agents.
+
+    An agent takes a finding and returns it (usually mutated). Keeping the return
+    explicit lets the engine chain agents in a pipeline.
+    """
+
+    name: str = ""
+
+    @abc.abstractmethod
+    def process(self, finding: Finding, ctx: AgentContext) -> Finding:
+        raise NotImplementedError
+
+    @staticmethod
+    def _uses_real_model(ctx: AgentContext) -> bool:
+        """True when a real language model backs the provider (not heuristic)."""
+        return ctx.ai.name != "heuristic"

argus/agents/enrichment.py

@@ -0,0 +1,111 @@
+"""Enrichment agent: fill the reasoning fields of a finding.
+
+Ensures every finding answers "why is this a vulnerability", "how would an
+attacker exploit it", and "what is the business impact". Scanners already provide
+these for their built-in rules; this agent fills gaps and, when a real model is
+configured, rewrites them with project-specific context.
+"""
+
+from __future__ import annotations
+
+from argus.agents.base import Agent, AgentContext
+from argus.ai.heuristic import HeuristicProvider
+from argus.core.models import Finding
+
+_SYSTEM = (
+    "You are a senior application security engineer. Given a vulnerability finding, "
+    "explain it precisely and without exaggeration. Be concrete and actionable. "
+    "Respond in three short sections labelled exactly: WHY, ATTACK, IMPACT."
+)
+
+
+class EnrichmentAgent(Agent):
+    name = "enrichment"
+
+    def process(self, finding: Finding, ctx: AgentContext) -> Finding:
+        # If the scanner already supplied full reasoning, leave it unless a real
+        # model can improve it with project context.
+        has_reasoning = all([finding.why_vulnerable, finding.attacker_perspective,
+                             finding.business_impact])
+
+        if self._uses_real_model(ctx):
+            if not has_reasoning or ctx.config.ai.enabled:
+                self._enrich_with_model(finding, ctx)
+            return finding
+
+        # Heuristic path: fill any missing fields from CWE templates.
+        if not has_reasoning:
+            self._enrich_heuristic(finding)
+        return finding
+
+    def _enrich_heuristic(self, finding: Finding) -> None:
+        for cwe in finding.cwe:
+            notes = HeuristicProvider.notes_for_cwe(cwe)
+            if notes:
+                finding.why_vulnerable = finding.why_vulnerable or notes["why"]
+                finding.attacker_perspective = (
+                    finding.attacker_perspective or notes["attack"])
+                finding.business_impact = finding.business_impact or notes["impact"]
+                return
+        # Generic fallback when no CWE template matches.
+        finding.why_vulnerable = finding.why_vulnerable or finding.description
+        finding.attacker_perspective = finding.attacker_perspective or (
+            "An attacker who reaches this code path can supply crafted input to "
+            "trigger the weakness described above.")
+        finding.business_impact = finding.business_impact or (
+            "Potential loss of confidentiality, integrity, or availability "
+            "depending on the data and privileges involved.")
+
+    def _enrich_with_model(self, finding: Finding, ctx: AgentContext) -> None:
+        prompt = self._build_prompt(finding, ctx)
+        try:
+            answer = ctx.ai.complete(_SYSTEM, prompt)
+        except Exception as exc:  # never let enrichment abort a scan
+            finding.metadata["enrichment_error"] = str(exc)
+            self._enrich_heuristic(finding)
+            return
+        sections = self._parse_sections(answer)
+        if sections.get("why"):
+            finding.why_vulnerable = sections["why"]
+        if sections.get("attack"):
+            finding.attacker_perspective = sections["attack"]
+        if sections.get("impact"):
+            finding.business_impact = sections["impact"]
+        if not any(sections.values()):
+            self._enrich_heuristic(finding)
+
+    @staticmethod
+    def _build_prompt(finding: Finding, ctx: AgentContext) -> str:
+        loc = finding.location
+        return (
+            f"Project: {ctx.project.name}\n"
+            f"Languages: {', '.join(ctx.project.languages) or 'unknown'}\n"
+            f"Frameworks: {', '.join(ctx.project.frameworks) or 'none detected'}\n\n"
+            f"Finding: {finding.title}\n"
+            f"Rule: {finding.rule_id}\n"
+            f"CWE: {', '.join(finding.cwe) or 'n/a'}  "
+            f"OWASP: {', '.join(finding.owasp) or 'n/a'}\n"
+            f"Location: {loc.as_ref()}\n"
+            f"Code:\n{loc.snippet or '(not available)'}\n\n"
+            "Explain this finding for the developer who owns this code."
+        )
+
+    @staticmethod
+    def _parse_sections(text: str) -> dict[str, str]:
+        out = {"why": "", "attack": "", "impact": ""}
+        current = None
+        for line in text.splitlines():
+            stripped = line.strip()
+            upper = stripped.upper()
+            if upper.startswith("WHY"):
+                current = "why"
+                stripped = stripped.split(":", 1)[-1].strip()
+            elif upper.startswith("ATTACK"):
+                current = "attack"
+                stripped = stripped.split(":", 1)[-1].strip()
+            elif upper.startswith("IMPACT"):
+                current = "impact"
+                stripped = stripped.split(":", 1)[-1].strip()
+            if current and stripped:
+                out[current] = (out[current] + " " + stripped).strip()
+        return out

argus/agents/exploit.py

@@ -0,0 +1,173 @@
+"""Attack Simulation agent.
+
+This is Argus's distinguishing feature. Rather than stating that an endpoint is
+vulnerable, it produces a safe, self-contained demonstration of the weakness:
+
+* how an attacker would discover it,
+* a step-by-step (read-only) exploit walkthrough,
+* what data would be exposed,
+* the business impact,
+* how the proposed fix blocks the attack, and
+* a before/after comparison.
+
+Safety: the simulation is *descriptive*. It never sends traffic to a live target
+and never executes generated exploit code. When a real model is used, the prompt
+constrains it to an educational, non-weaponized walkthrough. ``sandbox_ok`` marks
+that the demonstration was produced in this isolated, non-executing context.
+"""
+
+from __future__ import annotations
+
+from argus.agents.base import Agent, AgentContext
+from argus.core.models import ExploitScenario, Finding, Severity
+
+_SYSTEM = (
+    "You are a penetration tester writing an educational, defensive walkthrough for "
+    "the developer who owns the vulnerable code. Never produce a weaponized or "
+    "copy-paste-runnable exploit against live systems; illustrate the technique at a "
+    "level that teaches the risk and the fix. Use these exact section headers: "
+    "DISCOVERY, WALKTHROUGH, DATA_AT_RISK, BUSINESS_IMPACT, FIX_BLOCKS, BEFORE_AFTER."
+)
+
+# Templated scenarios keyed by primary CWE, used with the heuristic provider.
+_TEMPLATES: dict[str, dict[str, str]] = {
+    "CWE-89": {
+        "discovery": "Fuzz the parameter with a single quote. A resulting SQL error "
+                     "or changed response reveals the input reaches the query.",
+        "walk": "1. Observe a normal request. 2. Send `' OR '1'='1` in the parameter. "
+                "3. The WHERE clause becomes always-true, returning rows the user "
+                "should not see. 4. Escalate with UNION SELECT to read other tables.",
+        "data": "Any data reachable by the database user — often user records, "
+                "password hashes, tokens, and PII.",
+        "fix": "Parameterized queries bind input as data, so `' OR '1'='1` is treated "
+               "as a literal string and the query structure can no longer change.",
+        "ba": "Before: query text is built from input, so injected operators execute. "
+              "After: input is a bound parameter and cannot alter the statement.",
+    },
+    "CWE-78": {
+        "discovery": "Probe the input with a benign separator like `; id`. Command "
+                     "output appearing in the response confirms injection.",
+        "walk": "1. Identify the parameter that flows into a shell command. 2. Append "
+                "`; whoami`. 3. The extra command runs. 4. Escalate to fetch files or "
+                "open a reverse shell.",
+        "data": "Everything the application process can read, plus the ability to run "
+                "commands on the host.",
+        "fix": "Passing arguments as a list (no shell) removes the shell parser, so "
+               "metacharacters are treated as literal arguments.",
+        "ba": "Before: input is concatenated into a shell string. After: input is a "
+              "single argument value with no shell interpretation.",
+    },
+    "CWE-798": {
+        "discovery": "Grep the repository (including history) for key-like strings; the "
+                     "committed secret is found directly.",
+        "walk": "1. Clone the repo. 2. Search history for the credential. 3. Use it "
+                "against the corresponding service — no exploitation of the app needed.",
+        "data": "Whatever the credential unlocks: cloud account, database, payment or "
+                "email provider.",
+        "fix": "Rotating the secret invalidates the leaked value; loading it from a "
+               "secret manager keeps it out of source entirely.",
+        "ba": "Before: the live secret sits in version control. After: the code reads "
+              "it from the environment and the old value is revoked.",
+    },
+}
+
+
+class AttackSimulationAgent(Agent):
+    name = "attack-simulation"
+
+    # Only simulate meaningful findings; noise doesn't warrant a walkthrough.
+    MIN_SEVERITY = Severity.MEDIUM
+
+    def process(self, finding: Finding, ctx: AgentContext) -> Finding:
+        if finding.severity < self.MIN_SEVERITY:
+            return finding
+        if self._uses_real_model(ctx):
+            self._simulate_with_model(finding, ctx)
+        else:
+            self._simulate_heuristic(finding)
+        return finding
+
+    def _simulate_heuristic(self, finding: Finding) -> None:
+        tmpl = None
+        for cwe in finding.cwe:
+            if cwe in _TEMPLATES:
+                tmpl = _TEMPLATES[cwe]
+                break
+        if tmpl is None:
+            finding.exploit = ExploitScenario(
+                discovery=f"Identify the weak point described by {finding.rule_id} at "
+                          f"{finding.location.as_ref()}.",
+                exploit_walkthrough=finding.attacker_perspective or
+                    "Craft input that triggers the described weakness and observe the "
+                    "effect.",
+                data_at_risk=finding.business_impact or "Depends on the affected asset.",
+                business_impact=finding.business_impact,
+                fix_blocks_attack=(finding.remediation.summary
+                                   if finding.remediation else
+                                   "Applying the recommended fix removes the weakness."),
+                before_after="Before: the weakness is present. After: the fix removes "
+                             "the exploitable condition.",
+                sandbox_ok=True,
+            )
+            return
+        finding.exploit = ExploitScenario(
+            discovery=tmpl["discovery"],
+            exploit_walkthrough=tmpl["walk"],
+            data_at_risk=tmpl["data"],
+            business_impact=finding.business_impact or
+                "Direct impact on confidentiality and integrity of affected data.",
+            fix_blocks_attack=tmpl["fix"],
+            before_after=tmpl["ba"],
+            sandbox_ok=True,
+        )
+
+    def _simulate_with_model(self, finding: Finding, ctx: AgentContext) -> None:
+        prompt = (
+            f"Vulnerability: {finding.title}\n"
+            f"CWE: {', '.join(finding.cwe)}\n"
+            f"Location: {finding.location.as_ref()}\n"
+            f"Code:\n{finding.location.snippet or '(unavailable)'}\n\n"
+            "Write the educational attack simulation."
+        )
+        try:
+            answer = ctx.ai.complete(_SYSTEM, prompt)
+        except Exception as exc:
+            finding.metadata["simulation_error"] = str(exc)
+            self._simulate_heuristic(finding)
+            return
+        s = self._parse(answer)
+        finding.exploit = ExploitScenario(
+            discovery=s.get("discovery", ""),
+            exploit_walkthrough=s.get("walkthrough", ""),
+            data_at_risk=s.get("data_at_risk", ""),
+            business_impact=s.get("business_impact", finding.business_impact),
+            fix_blocks_attack=s.get("fix_blocks", ""),
+            before_after=s.get("before_after", ""),
+            sandbox_ok=True,
+        )
+        if not any([finding.exploit.discovery, finding.exploit.exploit_walkthrough]):
+            self._simulate_heuristic(finding)
+
+    @staticmethod
+    def _parse(text: str) -> dict[str, str]:
+        headers = {
+            "DISCOVERY": "discovery",
+            "WALKTHROUGH": "walkthrough",
+            "DATA_AT_RISK": "data_at_risk",
+            "BUSINESS_IMPACT": "business_impact",
+            "FIX_BLOCKS": "fix_blocks",
+            "BEFORE_AFTER": "before_after",
+        }
+        out: dict[str, str] = {}
+        current = None
+        for line in text.splitlines():
+            stripped = line.strip()
+            matched = next((v for k, v in headers.items()
+                            if stripped.upper().startswith(k)), None)
+            if matched:
+                current = matched
+                rest = stripped.split(":", 1)[-1].strip() if ":" in stripped else ""
+                out[current] = rest
+            elif current and stripped:
+                out[current] = (out.get(current, "") + " " + stripped).strip()
+        return out

argus/agents/patch.py

@@ -0,0 +1,82 @@
+"""Patch generation agent.
+
+Proposes a concrete fix as a unified diff and, where possible, verifies it. Two
+paths:
+
+* **Deterministic rewrites** for a set of well-understood rules (e.g. unsafe
+  ``yaml.load`` → ``yaml.safe_load``). These are self-verifying: Argus re-runs the
+  triggering pattern against the rewritten line and only marks the patch
+  ``verified`` if the detection no longer fires — a fast, local proxy for "the fix
+  resolves the issue without obviously breaking the line".
+* **Model-generated patches** when a real provider is configured, for findings
+  without a deterministic rewrite. These are proposed but left unverified unless a
+  re-scan confirms them.
+
+The agent only proposes changes; it never writes to the working tree. Applying a
+patch and opening a pull request is an explicit, separate action.
+"""
+
+from __future__ import annotations
+
+import re
+
+from argus.agents.base import Agent, AgentContext
+from argus.core.models import Finding, Remediation
+from argus.remediation.rewrites import fix_line, verify_line_fixed
+
+_SYSTEM = (
+    "You are a secure-coding assistant. Given a vulnerable code snippet and the "
+    "issue, return ONLY a minimal corrected version of the snippet that resolves "
+    "the vulnerability while preserving behavior. Do not add commentary."
+)
+
+
+class PatchAgent(Agent):
+    name = "patch"
+
+    def process(self, finding: Finding, ctx: AgentContext) -> Finding:
+        if finding.remediation is None:
+            finding.remediation = Remediation(summary="See remediation guidance.")
+
+        original = finding.location.snippet or ""
+        fixed = fix_line(finding.rule_id, original)
+        verified = False
+
+        if fixed and fixed != original:
+            verified = verify_line_fixed(finding.rule_id, fixed)
+        elif self._uses_real_model(ctx) and original:
+            fixed = self._model_fix(finding, ctx, original)
+
+        if fixed and fixed != original:
+            finding.remediation.patch = self._unified_diff(
+                finding.location.path, original, fixed,
+                start_line=finding.location.start_line or 1)
+            finding.remediation.verified = verified
+        return finding
+
+    def _model_fix(self, finding: Finding, ctx: AgentContext, original: str) -> str | None:
+        prompt = (
+            f"Issue: {finding.title} ({', '.join(finding.cwe)})\n"
+            f"File: {finding.location.path}\n"
+            f"Vulnerable snippet:\n{original}\n\n"
+            "Return the corrected snippet only."
+        )
+        try:
+            out = ctx.ai.complete(_SYSTEM, prompt).strip()
+        except Exception as exc:
+            finding.metadata["patch_error"] = str(exc)
+            return None
+        # Strip code fences if the model added them.
+        out = re.sub(r"^```[a-zA-Z]*\n?|\n?```$", "", out).strip()
+        return out or None
+
+    @staticmethod
+    def _unified_diff(path: str, before: str, after: str, start_line: int) -> str:
+        """A compact unified diff for a single changed line/snippet."""
+        return (
+            f"--- a/{path}\n"
+            f"+++ b/{path}\n"
+            f"@@ -{start_line} +{start_line} @@\n"
+            f"-{before}\n"
+            f"+{after}\n"
+        )

argus/ai/__init__.py

@@ -0,0 +1,16 @@
+"""AI provider abstraction.
+
+Argus supports multiple model backends behind one interface so organizations can
+choose where their code goes:
+
+* ``heuristic`` — no network, no keys; template-based enrichment. The default.
+* ``anthropic`` / ``openai`` — cloud-hosted models.
+* ``ollama`` — local models, keeping source inside your own environment.
+
+Providers are plugins like everything else and register on import.
+"""
+
+from argus.ai.base import AIProvider, ChatMessage
+from argus.ai.factory import build_provider
+
+__all__ = ["AIProvider", "ChatMessage", "build_provider"]

argus/ai/anthropic_provider.py

@@ -0,0 +1,47 @@
+"""Anthropic (Claude) provider.
+
+Uses the official ``anthropic`` SDK if installed and ``ANTHROPIC_API_KEY`` is set.
+Import of the SDK is deferred to :meth:`complete` so the module loads even when
+the optional dependency is absent — availability is reported by ``is_available``.
+"""
+
+from __future__ import annotations
+
+import os
+
+from argus.ai.base import AIProvider
+from argus.core.plugin import ai_provider
+
+
+@ai_provider
+class AnthropicProvider(AIProvider):
+    name = "anthropic"
+    is_remote = True
+    # A current, capable default; override via config `ai.model`.
+    default_model = "claude-sonnet-5"
+
+    @classmethod
+    def is_available(cls) -> bool:
+        if not os.environ.get("ANTHROPIC_API_KEY"):
+            return False
+        try:
+            import anthropic  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    def complete(self, system: str, user: str) -> str:
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+        resp = client.messages.create(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        # Concatenate text blocks from the response content.
+        return "".join(
+            block.text for block in resp.content if getattr(block, "type", "") == "text"
+        ).strip()

argus/ai/base.py

@@ -0,0 +1,62 @@
+"""The AIProvider contract and shared helpers.
+
+An AI provider is a thin, uniform wrapper around a chat-style model. Agents call
+:meth:`AIProvider.complete` with a system prompt and a user prompt and get back
+text. Everything provider-specific (auth, endpoints, request shape) lives in the
+concrete subclasses.
+"""
+
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass
+from typing import ClassVar
+
+
+@dataclass
+class ChatMessage:
+    role: str  # "system" | "user" | "assistant"
+    content: str
+
+
+class AIProvider(abc.ABC):
+    """Base class for all model backends."""
+
+    #: Unique provider id used in config and the `--ai-provider` flag.
+    name: ClassVar[str] = ""
+    #: Whether this provider sends data off the local machine. Surfaced to users
+    #: so they can make an informed choice about source-code confidentiality.
+    is_remote: ClassVar[bool] = True
+    #: Default model id when the user doesn't specify one.
+    default_model: ClassVar[str] = ""
+
+    def __init__(self, model: str | None = None, *, temperature: float = 0.0,
+                 max_tokens: int = 1500) -> None:
+        self.model = model or self.default_model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Return True if this provider can actually be used (SDK + creds present).
+
+        The heuristic provider is always available; cloud/local providers check
+        for their SDK and credentials. Used to fall back gracefully.
+        """
+        return True
+
+    @abc.abstractmethod
+    def complete(self, system: str, user: str) -> str:
+        """Return the model's completion for a system + user prompt."""
+        raise NotImplementedError
+
+    def chat(self, messages: list[ChatMessage]) -> str:
+        """Multi-turn convenience wrapper. Providers may override for efficiency.
+
+        The default flattens the conversation into a single system+user call,
+        which is enough for Argus's mostly single-shot agent prompts.
+        """
+        system = "\n\n".join(m.content for m in messages if m.role == "system")
+        convo = "\n\n".join(f"{m.role.upper()}: {m.content}"
+                            for m in messages if m.role != "system")
+        return self.complete(system, convo)

argus/ai/factory.py

@@ -0,0 +1,47 @@
+"""Provider selection with graceful fallback.
+
+``build_provider`` honors the requested provider but never hard-fails a scan just
+because a model backend is missing: if the requested cloud/local provider is
+unavailable (no SDK, no key, no server), it warns and falls back to the offline
+heuristic provider so ``argus scan`` still produces a report.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+# Importing the provider modules is what registers them in the registry.
+from argus.ai import (  # noqa: F401
+    anthropic_provider,
+    heuristic,
+    ollama_provider,
+    openai_provider,
+)
+from argus.ai.base import AIProvider
+from argus.core.config import AIConfig
+from argus.core.plugin import registry
+
+
+def build_provider(cfg: AIConfig) -> AIProvider:
+    providers = registry.ai_providers()
+    requested = cfg.provider
+
+    if requested not in providers:
+        warnings.warn(
+            f"Unknown AI provider {requested!r}; using 'heuristic'. "
+            f"Available: {sorted(providers)}",
+            stacklevel=2,
+        )
+        requested = "heuristic"
+
+    cls = providers[requested]
+    if not cls.is_available():
+        if requested != "heuristic":
+            warnings.warn(
+                f"AI provider {requested!r} is not available "
+                f"(missing SDK, credentials, or server). Falling back to 'heuristic'.",
+                stacklevel=2,
+            )
+        cls = providers["heuristic"]
+
+    return cls(model=cfg.model, temperature=cfg.temperature, max_tokens=cfg.max_tokens)