codejury 0.1.0__py3-none-any.whl

codejury/data/capabilities/input_validation.yaml

@@ -0,0 +1,92 @@
+id: input_validation
+name: Input Validation
+asvs_chapter: V5
+description: >-
+  The inbound trust boundary. Untrusted input must be parameterized, validated
+  against an allowlist, or escaped before it reaches an interpreter (SQL, shell,
+  filesystem, template, LDAP, ...).
+
+sub_capabilities:
+  sql_injection:
+    correct_patterns:
+      - id: SQLI-OK-1
+        description: Use parameterized queries or ORM-bound parameters; never build SQL from input
+        signals: ["cursor.execute(", "execute(query, params", "session.query(", "text(:param)"]
+        why_ok: The driver sends data separately from the statement, so input cannot alter the query
+
+    anti_patterns:
+      - id: SQLI-BAD-1
+        cwe: CWE-89
+        severity: CRITICAL
+        description: Build SQL by string concatenation or f-string interpolation of input
+        signals: ['execute(f"', 'execute("SELECT', '" + ', "% (", ".format("]
+        why_bad: Input becomes part of the statement and can change its meaning entirely
+        example_bad: |
+          cursor.execute(f"SELECT * FROM users WHERE name = '{name}'")
+        example_good: |
+          cursor.execute("SELECT * FROM users WHERE name = %s", (name,))
+
+      - id: SQLI-BAD-2
+        cwe: CWE-89
+        severity: HIGH
+        description: Interpolate a table or column name from input without an allowlist
+        why_bad: Identifiers cannot be parameterized, so unchecked input still injects
+
+      - id: SQLI-BAD-3
+        cwe: CWE-89
+        severity: HIGH
+        description: Pass a pre-built SQL string to an ORM raw or text escape hatch
+        signals: [".raw(", "text(", "execute_sql("]
+        why_bad: Raw escape hatches bypass the ORM's parameter binding
+
+  command_injection:
+    correct_patterns:
+      - id: CMDI-OK-1
+        description: Run subprocesses with an argument list and shell=False
+        signals: ["subprocess.run([", "subprocess.Popen(["]
+        why_ok: Arguments are passed directly to execve, so the shell never parses input
+
+    anti_patterns:
+      - id: CMDI-BAD-1
+        cwe: CWE-78
+        severity: CRITICAL
+        description: Invoke a shell with an interpolated command string
+        signals: ["os.system(", "shell=True", "os.popen("]
+        why_bad: Shell metacharacters in input let an attacker run arbitrary commands
+        example_bad: |
+          os.system("ping " + host)
+        example_good: |
+          subprocess.run(["ping", "-c", "1", host], shell=False)
+
+      - id: CMDI-BAD-2
+        cwe: CWE-78
+        severity: HIGH
+        description: Build the argument list itself from an unvalidated, shell-parsed string
+        signals: ["shlex.split(", "shell=True"]
+        why_bad: Splitting an untrusted string can still smuggle extra arguments or commands
+
+  path_traversal:
+    correct_patterns:
+      - id: PATH-OK-1
+        description: Resolve the path and confirm it stays within an allowed base directory
+        signals: ["os.path.realpath", "Path(...).resolve()", "is_relative_to("]
+        why_ok: A resolved path outside the base is rejected before any file access
+
+    anti_patterns:
+      - id: PATH-BAD-1
+        cwe: CWE-22
+        severity: HIGH
+        description: Join user input into a filesystem path without containment checks
+        signals: ["os.path.join(", "open(", "Path("]
+        why_bad: Sequences like ../ let input escape the intended directory
+        example_bad: |
+          open(os.path.join(UPLOAD_DIR, filename))
+        example_good: |
+          target = (UPLOAD_DIR / filename).resolve()
+          if not target.is_relative_to(UPLOAD_DIR):
+              raise ValueError("path escapes upload dir")
+
+trigger_signals:
+  - raw SQL strings or cursor.execute calls appear
+  - imports of os, subprocess, or shlex with process execution
+  - file paths built from request, form, or query parameters

codejury/data/capabilities/output_encoding.yaml

@@ -0,0 +1,56 @@
+id: output_encoding
+name: Output Encoding
+asvs_chapter: V5
+description: The outbound trust boundary. Untrusted data must be encoded for the context it is rendered into.
+
+sub_capabilities:
+  xss:
+    correct_patterns:
+      - id: XSS-OK-1
+        description: Rely on contextual output encoding or framework auto-escaping; render untrusted data as text, not markup
+        signals: ["escape(", "textContent", "render_template"]
+        why_ok: Data is encoded for its context, so it cannot become executable markup
+
+    anti_patterns:
+      - id: XSS-BAD-1
+        cwe: CWE-79
+        severity: HIGH
+        description: Render untrusted input into HTML through a raw sink
+        signals: ["innerHTML", "dangerouslySetInnerHTML", "|safe", "mark_safe(", "v-html"]
+        why_bad: Attacker-supplied markup runs as script in the victim's browser
+        example_bad: |
+          el.innerHTML = "Hello " + username
+        example_good: |
+          el.textContent = "Hello " + username
+
+      - id: XSS-BAD-2
+        cwe: CWE-79
+        severity: HIGH
+        description: Build HTML by string concatenation of untrusted input
+        why_bad: Same XSS sink, just assembled by hand
+
+      - id: XSS-BAD-3
+        cwe: CWE-116
+        severity: MEDIUM
+        description: Disable template auto-escaping globally
+        signals: ["autoescape=False", "| safe"]
+        why_bad: Every template output becomes a potential injection point
+
+  header_and_log:
+    anti_patterns:
+      - id: HDR-BAD-1
+        cwe: CWE-113
+        severity: MEDIUM
+        description: Place untrusted input into a response header or redirect location without sanitizing newlines
+        why_bad: CR/LF in the value splits the response or injects headers
+
+      - id: LOG-BAD-1
+        cwe: CWE-117
+        severity: LOW
+        description: Write untrusted input to logs without neutralizing newlines or control characters
+        why_bad: Forged log lines mislead investigators and can poison log processors
+
+trigger_signals:
+  - HTML sinks like innerHTML, dangerouslySetInnerHTML, |safe, mark_safe, v-html
+  - templates rendering request data
+  - response headers or redirect targets built from input

codejury/data/capabilities/secrets.yaml

@@ -0,0 +1,51 @@
+id: secrets
+name: Secrets Management
+asvs_chapter: V6
+description: How credentials and keys are stored, supplied, and kept out of code, logs, and version control.
+
+sub_capabilities:
+  storage:
+    correct_patterns:
+      - id: SEC-OK-1
+        description: Load secrets at runtime from environment variables or a secret manager
+        signals: ["os.environ[", "os.getenv(", "secretsmanager", "vault"]
+        why_ok: Secrets live outside the codebase and can be rotated without a deploy
+
+    anti_patterns:
+      - id: SEC-BAD-1
+        cwe: CWE-798
+        severity: HIGH
+        description: Hardcode an API key, token, or other credential in source
+        signals: ["api_key = \"", "token = \"", "aws_secret_access_key ="]
+        why_bad: The credential leaks with the source and cannot be rotated easily
+        example_bad: |
+          STRIPE_KEY = "sk_live_4eC39Hq..."
+        example_good: |
+          STRIPE_KEY = os.environ["STRIPE_KEY"]
+
+      - id: SEC-BAD-2
+        cwe: CWE-259
+        severity: HIGH
+        description: Hardcode a password
+        signals: ["password = \"", "passwd = \""]
+        why_bad: A fixed password in code is shared, discoverable, and unchangeable
+
+  exposure:
+    anti_patterns:
+      - id: SEC-BAD-3
+        cwe: CWE-532
+        severity: MEDIUM
+        description: Write secrets or tokens to logs
+        signals: ["log.info(token", "print(password", "logger.debug(secret"]
+        why_bad: Logs are widely accessible and long-lived, so logged secrets spread
+
+      - id: SEC-BAD-4
+        cwe: CWE-540
+        severity: MEDIUM
+        description: Commit secrets in config files or a tracked .env
+        why_bad: Version history keeps the secret even after it is removed
+
+trigger_signals:
+  - assignments named key, token, password, secret, or credential
+  - imports of a secret manager or vault client
+  - .env or config files with credential-looking keys

codejury/data/capabilities/session.yaml

@@ -0,0 +1,60 @@
+id: session
+name: Session Management
+asvs_chapter: V3
+description: Establishing, protecting, and ending the context that links requests to an authenticated user.
+
+sub_capabilities:
+  cookie_attributes:
+    correct_patterns:
+      - id: COOKIE-OK-1
+        description: Set HttpOnly, Secure, and an explicit SameSite on session cookies
+        signals: ["httponly=True", "secure=True", "samesite="]
+        why_ok: Blocks script access, plaintext transmission, and most cross-site sending
+
+    anti_patterns:
+      - id: COOKIE-BAD-1
+        cwe: CWE-1004
+        severity: MEDIUM
+        description: Session cookie set without HttpOnly
+        signals: ["set_cookie("]
+        why_bad: JavaScript can read the cookie, so an XSS turns into session theft
+        example_bad: |
+          resp.set_cookie("sid", token)
+        example_good: |
+          resp.set_cookie("sid", token, httponly=True, secure=True, samesite="Lax")
+
+      - id: COOKIE-BAD-2
+        cwe: CWE-614
+        severity: MEDIUM
+        description: Session cookie set without Secure
+        why_bad: The cookie is sent over plain HTTP and can be sniffed
+
+      - id: COOKIE-BAD-3
+        cwe: CWE-1275
+        severity: LOW
+        description: SameSite unset, or None without a documented cross-site need
+        why_bad: Widens the CSRF surface
+
+  lifecycle:
+    correct_patterns:
+      - id: SESS-OK-1
+        description: Regenerate the session id at login, invalidate it at logout, and enforce idle and absolute timeouts
+        why_ok: Limits the window an stolen or fixated session is useful
+
+    anti_patterns:
+      - id: SESS-BAD-1
+        cwe: CWE-384
+        severity: HIGH
+        description: Do not rotate the session id after authentication (session fixation)
+        why_bad: An attacker who plants a known session id before login rides it afterward
+
+      - id: SESS-BAD-2
+        cwe: CWE-613
+        severity: MEDIUM
+        description: No session expiry or an unbounded lifetime
+        why_bad: A leaked session stays valid indefinitely
+
+trigger_signals:
+  - set_cookie or Set-Cookie on a session token
+  - login, logout, or session creation handlers
+  - a session store or framework session configuration

codejury/data/golden/authn_bcrypt_password.yaml

@@ -0,0 +1,5 @@
+capability: authn
+vulnerable: false
+code: |
+  def store_password(pwd: str) -> bytes:
+      return bcrypt.hashpw(pwd.encode(), bcrypt.gensalt())

codejury/data/golden/authn_sha256_password.yaml

@@ -0,0 +1,5 @@
+capability: authn
+vulnerable: true
+code: |
+  def store_password(pwd: str) -> str:
+      return hashlib.sha256(pwd.encode()).hexdigest()

codejury/data/golden/sqli_fstring_query.yaml

@@ -0,0 +1,5 @@
+capability: input_validation
+vulnerable: true
+code: |
+  def find_user(name: str):
+      cursor.execute(f"SELECT * FROM users WHERE name = '{name}'")

codejury/data/golden/sqli_parameterized_query.yaml

@@ -0,0 +1,5 @@
+capability: input_validation
+vulnerable: false
+code: |
+  def find_user(name: str):
+      cursor.execute("SELECT * FROM users WHERE name = %s", (name,))

codejury/data/tasks/audit_diff_debate.yaml

@@ -0,0 +1,4 @@
+name: audit_diff_debate
+orchestrator: debate
+provider: anthropic
+# capabilities omitted -> check all of them

codejury/data/tasks/quick_scan_single.yaml

@@ -0,0 +1,4 @@
+name: quick_scan_single
+orchestrator: single
+provider: anthropic
+capabilities: [authn, input_validation, secrets]

codejury/domain/__init__.py

@@ -0,0 +1,5 @@
+"""codejury.domain -- the framework's typed data model.
+
+Layers communicate only through these structures; this package depends on no
+concrete implementation (Provider / Source / ...).
+"""

codejury/domain/artifact.py

@@ -0,0 +1,20 @@
+"""CodeArtifact -- the unit of code an agent analyzes.
+
+Produced by a Source (diff hunk, file, function, repo chunk) and consumed by an
+agent. It is cross-layer typed data, so it lives in ``domain`` rather than in
+``sources``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ArtifactKind = Literal["diff", "file", "function", "repo"]
+
+
+@dataclass(frozen=True, kw_only=True)
+class CodeArtifact:
+    kind: ArtifactKind
+    path: str       # identifier used when building Evidence references
+    content: str    # the diff/file/function text the agent analyzes

codejury/domain/capability.py

@@ -0,0 +1,123 @@
+"""Capability model -- domain knowledge loaded from YAML into typed dataclasses.
+
+A capability is the first-class unit of Application Security knowledge, one per
+OWASP ASVS area. Its YAML is readable by the model as a checklist, by a rule
+engine because ``signals`` can be grepped, and by a human because the ``why_*``
+fields are teaching material.
+
+This module only deserializes YAML into dataclasses; it holds no audit logic.
+Unknown keys in the YAML are ignored so the schema can grow without breaking
+older loaders.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from codejury.domain.observation import Severity
+
+
+@dataclass(frozen=True, kw_only=True)
+class CorrectPattern:
+    """A safe pattern. Matching it supports a SECURE verdict."""
+
+    id: str
+    description: str = ""
+    signals: list[str] = field(default_factory=list)  # code markers a rule engine can grep
+    why_ok: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CorrectPattern:
+        return cls(
+            id=data["id"],
+            description=data.get("description", ""),
+            signals=list(data.get("signals", [])),
+            why_ok=data.get("why_ok", ""),
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class AntiPattern:
+    """An unsafe pattern. Matching it supports a VULNERABLE verdict."""
+
+    id: str
+    description: str = ""
+    signals: list[str] = field(default_factory=list)
+    cwe: str = ""
+    severity: Severity = "MEDIUM"
+    why_bad: str = ""
+    example_bad: str = ""
+    example_good: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AntiPattern:
+        return cls(
+            id=data["id"],
+            description=data.get("description", ""),
+            signals=list(data.get("signals", [])),
+            cwe=data.get("cwe", ""),
+            severity=data.get("severity", "MEDIUM"),
+            why_bad=data.get("why_bad", ""),
+            example_bad=data.get("example_bad", ""),
+            example_good=data.get("example_good", ""),
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class SubCapability:
+    """One checkable dimension within a capability, such as password_storage."""
+
+    name: str
+    correct_patterns: list[CorrectPattern] = field(default_factory=list)
+    anti_patterns: list[AntiPattern] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, Any]) -> SubCapability:
+        return cls(
+            name=name,
+            correct_patterns=[CorrectPattern.from_dict(p) for p in data.get("correct_patterns", [])],
+            anti_patterns=[AntiPattern.from_dict(p) for p in data.get("anti_patterns", [])],
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class Capability:
+    """A first-class Application Security knowledge unit, one per OWASP ASVS area."""
+
+    id: str
+    name: str
+    asvs_chapter: str = ""
+    description: str = ""
+    sub_capabilities: dict[str, SubCapability] = field(default_factory=dict)
+    # code patterns that bring this capability into scope for a given artifact
+    trigger_signals: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Capability:
+        subs = data.get("sub_capabilities") or {}
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            asvs_chapter=data.get("asvs_chapter", ""),
+            description=data.get("description", ""),
+            sub_capabilities={name: SubCapability.from_dict(name, body) for name, body in subs.items()},
+            trigger_signals=list(data.get("trigger_signals", [])),
+        )
+
+
+def load_capability(path: str | Path) -> Capability:
+    """Load a single capability YAML file into a Capability."""
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a YAML mapping at the top level, got {type(data).__name__}")
+    return Capability.from_dict(data)
+
+
+def load_capabilities(directory: str | Path) -> list[Capability]:
+    """Load every ``*.yaml`` capability file in a directory, sorted by name."""
+    return [load_capability(p) for p in sorted(Path(directory).glob("*.yaml"))]

codejury/domain/context.py

@@ -0,0 +1,26 @@
+"""AnalysisContext -- the input an agent reads on a single run.
+
+An orchestrator builds one of these (selecting which capabilities apply to the
+artifact) and passes it to ``Agent.run``. Keeping capabilities inside the
+context lets the agent signature stay ``run(ctx)``.
+
+For multi-round orchestration (debate, reflexion) the orchestrator threads prior
+observations through ``history`` and the current ``round_num``; single-pass
+strategies leave them at their defaults.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from codejury.domain.artifact import CodeArtifact
+from codejury.domain.capability import Capability
+from codejury.domain.observation import Observation
+
+
+@dataclass(frozen=True, kw_only=True)
+class AnalysisContext:
+    artifact: CodeArtifact
+    capabilities: list[Capability]
+    history: list[Observation] = field(default_factory=list)
+    round_num: int = 0

codejury/domain/observation.py

@@ -0,0 +1,104 @@
+"""Observation model -- the unit agents produce and orchestrators consume.
+
+A single ``agent.run`` yields a list of ``Observation`` values, each one a
+``Finding``, ``Verdict``, or ``Concession``.
+
+``Verdict`` is the important one: it is emitted whether the code matches an
+anti-pattern (VULNERABLE) or a safe pattern (SECURE), so a report can explain
+both "why this is wrong" and "why this is fine". A capability is a checkup
+dimension, not just an anomaly filter.
+
+All classes are ``kw_only`` dataclasses to avoid default-ordering problems
+across subclass inheritance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, ClassVar, Literal
+
+Severity = Literal["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"]
+
+VerdictStatus = Literal[
+    "SECURE",       # matched a safe pattern; confirmed not vulnerable here
+    "VULNERABLE",   # matched an anti-pattern; confirmed vulnerable
+    "PARTIAL",      # partially in place (e.g. validation present but incomplete)
+    "NOT_PRESENT",  # dimension does not apply to / does not appear in this code
+    "UNKNOWN",      # insufficient evidence to decide
+]
+
+ObservationKind = Literal["finding", "verdict", "concession"]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Evidence:
+    """A reference to a concrete code location backing a judgement."""
+
+    file: str
+    line: int | None = None
+    end_line: int | None = None
+    code: str = ""
+
+
+@dataclass(kw_only=True)
+class Observation:
+    """Base class carrying provenance shared by every observation."""
+
+    capability: str = ""        # e.g. "authn.password_storage"
+    produced_by: str = ""       # agent role that produced it, e.g. "verifier"
+    round_num: int = 0          # round index in multi-round orchestration
+
+    kind: ClassVar[ObservationKind] = "finding"
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["kind"] = self.kind  # ClassVar, so asdict() omits it; add explicitly
+        return data
+
+
+@dataclass(kw_only=True)
+class Finding(Observation):
+    """A vulnerability claim (produced by Finder / Challenger)."""
+
+    title: str
+    description: str = ""
+    severity: Severity = "MEDIUM"
+    cwe: str = ""
+    evidence: list[Evidence] = field(default_factory=list)
+    recommendation: str = ""
+    matched_anti: list[str] = field(default_factory=list)  # anti_pattern ids hit
+    confidence: float = 0.5
+
+    kind: ClassVar[ObservationKind] = "finding"
+
+
+@dataclass(kw_only=True)
+class Verdict(Observation):
+    """A ruling on one capability over a piece of code (produced by Verifier).
+
+    Expresses both "vulnerable here" and "fine here" -- the key to answering
+    "why is this not a problem".
+    """
+
+    status: VerdictStatus
+    reasoning: str = ""
+    evidence: list[Evidence] = field(default_factory=list)
+    matched_correct: list[str] = field(default_factory=list)  # correct_pattern ids hit
+    matched_anti: list[str] = field(default_factory=list)      # anti_pattern ids hit
+    confidence: float = 0.5
+
+    kind: ClassVar[ObservationKind] = "verdict"
+
+
+@dataclass(kw_only=True)
+class Concession(Observation):
+    """A position that an earlier claim should be withdrawn or dismissed, with reason.
+
+    Covers both a finder conceding its own finding and a challenger or judge
+    moving to dismiss one. ``target`` identifies the claim (a Finding title).
+    """
+
+    target: str
+    reason: str = ""
+
+    kind: ClassVar[ObservationKind] = "concession"

codejury/domain/result.py

@@ -0,0 +1,19 @@
+"""AnalysisResult -- what an orchestrator returns.
+
+Orchestrator-agnostic: it carries the observations produced over a run, plus an
+optional error so a partial failure can be reported without raising. Anything
+strategy-specific (debate convergence, rounds) is added when that orchestrator
+needs it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from codejury.domain.observation import Observation
+
+
+@dataclass(kw_only=True)
+class AnalysisResult:
+    observations: list[Observation] = field(default_factory=list)
+    error: str | None = None