codejury 0.2.0__tar.gz → 0.4.0__tar.gz

codejury-0.4.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: codejury
+Version: 0.4.0
+Summary: General-purpose Application Security AI audit framework -- five-layer architecture, capabilities as first-class data
+Author: 4234288
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/4234288/codejury
+Project-URL: Repository, https://github.com/4234288/codejury
+Keywords: security,appsec,static analysis,llm,owasp,asvs,code review
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == "litellm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# codejury
+
+An AI security auditor for code whose knowledge lives in versioned YAML, not in
+prompts. It reviews a diff or a whole repository against the OWASP ASVS and
+reports a verdict per dimension -- both what is **vulnerable** and what is
+**verified safe**.
+
+The name is the core idea: code goes before a "jury" of adversarial roles --
+Finder / Challenger / Judge -- that argue and converge on a verdict.
+
+Why it is built this way:
+
+- **Knowledge is data.** Each of the 11 OWASP ASVS areas is a YAML capability
+  (safe patterns + anti-patterns, with CWE and examples) -- versioned, reviewable
+  in a PR, and editable by non-engineers. The framework core stays small.
+- **Verdicts, not just alerts.** Every capability yields `SECURE` / `VULNERABLE`
+  / `PARTIAL` / `NOT_PRESENT`, so a report shows what was checked and *passed*,
+  not only what failed.
+- **Composable.** Four orchestration strategies, four model backends, and
+  diff / repo inputs are chosen per run -- mix and match.
+
+## Install
+
+```bash
+pip install codejury                 # core + CLI
+pip install 'codejury[anthropic]'    # the provider you'll use: anthropic | openai | litellm
+```
+
+## Quickstart
+
+```bash
+# No API key needed -- prove the pipeline runs end to end with mock layers
+codejury dry-run
+
+# A real audit: set a key, then review your staged changes
+export ANTHROPIC_API_KEY=sk-ant-...
+git diff | codejury audit --provider anthropic
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `codejury dry-run` | Run the mock pipeline with no key (smoke test). |
+| `codejury audit [diff]` | Audit a unified diff from a file or stdin (`-`). |
+| `codejury scan <dir>` | Audit a whole directory tree, capability by capability. |
+| `codejury run <task>` | Run a named task preset (see [Tasks](#tasks)). |
+| `codejury eval` | Score the golden cases and report precision / recall. |
+
+Shared flags: `--orchestrator {single,pipeline,debate,reflexion}`,
+`--provider {anthropic,openai,litellm}`, `--model`, `--format {text,markdown,json}`.
+
+```bash
+# Multi-round adversarial debate, rendered as Markdown
+git diff | codejury audit --orchestrator debate --format markdown - > report.md
+
+# Deep whole-repo scan, scoped to a few capabilities to bound the cost
+codejury scan ./myrepo --only secrets,input_validation,crypto
+```
+
+## Configuration
+
+Provider keys are read from the environment (codejury does **not** auto-load
+`.env` -- copy `.env.example` and `source` it):
+
+| Variable | Used by |
+|---|---|
+| `ANTHROPIC_API_KEY` | `--provider anthropic` |
+| `OPENAI_API_KEY` | `--provider openai` |
+| `CODEJURY_API_BASE` / `CODEJURY_API_KEY` / `CODEJURY_MODEL` | defaults for `--api-base` / `--api-key` / `--model` (any provider) |
+
+The `CODEJURY_*` overrides make a LiteLLM proxy a one-liner:
+
+```bash
+# with CODEJURY_API_BASE / CODEJURY_API_KEY / CODEJURY_MODEL in a sourced .env
+git diff | codejury audit --provider litellm -
+```
+
+## Tasks
+
+A task is a named preset (capabilities + orchestrator + provider + model). It
+lives in a YAML file; the API key always stays in the environment.
+
+```yaml
+# mytasks/proxy_scan.yaml  ->  codejury run proxy_scan --tasks mytasks
+name: proxy_scan
+orchestrator: debate
+provider: litellm
+model: your-alias
+api_base: https://litellm.example.com   # key from CODEJURY_API_KEY
+capabilities: [authn, input_validation, secrets]   # omit to check all
+```
+
+## Capabilities
+
+The library covers all 11 OWASP ASVS areas, one YAML each under
+`codejury/data/capabilities/`. These ids are what `--only` and a task's
+`capabilities:` accept:
+
+`authn` · `authz` · `session` · `input_validation` · `output_encoding` ·
+`crypto` · `secrets` · `data_protection` · `error_logging` ·
+`business_logic` · `dependency_config`
+
+To tune for your codebase, edit these files (add patterns / sharpen wording) --
+no code change needed.
+
+## Architecture
+
+```
+Layer 5  Task            preset: source + capabilities + orchestrator + agents
+Layer 4  Capability      YAML domain knowledge (authn / authz / ...)
+Layer 3  Orchestrator    strategy (single / pipeline / debate / reflexion)
+         Source          input (diff / repo / function)
+         Agent           role (finder / challenger / judge / verifier)
+Layer 2  Provider        model backend (anthropic / openai / litellm / mock)
+Layer 1  Infrastructure  cross-cutting utilities (json parsing, retry, ...)
+```
+
+Layers talk only through typed data, and each is an abstract base class plus
+implementations, so the axes (task / orchestration / model / input) compose
+independently.
+
+## Limitations
+
+- **Prompts are a first pass.** Expect false positives and misses on real code.
+  Tune by editing the capability YAML and growing the golden set; measure the
+  effect with `codejury eval`.
+- **Local-pattern checks are sharper than data-flow ones.** Capabilities judged
+  from one spot (weak crypto, hardcoded secrets) are reliable; taint / data-flow
+  ones like path traversal over-flag in single-file review because the verifier
+  can't see whether a value is attacker-controlled. `scan --callers` adds
+  cross-file call sites for provenance (helps some cases, not a full fix); also
+  scope with `--only` or challenge findings with `--orchestrator debate`.
+- **`scan` cost scales as files x capabilities.** It is a periodic deep audit,
+  not a quick check -- scope it with `--only`. Day to day, audit the diff.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

codejury-0.4.0/README.md

@@ -0,0 +1,143 @@
+# codejury
+
+An AI security auditor for code whose knowledge lives in versioned YAML, not in
+prompts. It reviews a diff or a whole repository against the OWASP ASVS and
+reports a verdict per dimension -- both what is **vulnerable** and what is
+**verified safe**.
+
+The name is the core idea: code goes before a "jury" of adversarial roles --
+Finder / Challenger / Judge -- that argue and converge on a verdict.
+
+Why it is built this way:
+
+- **Knowledge is data.** Each of the 11 OWASP ASVS areas is a YAML capability
+  (safe patterns + anti-patterns, with CWE and examples) -- versioned, reviewable
+  in a PR, and editable by non-engineers. The framework core stays small.
+- **Verdicts, not just alerts.** Every capability yields `SECURE` / `VULNERABLE`
+  / `PARTIAL` / `NOT_PRESENT`, so a report shows what was checked and *passed*,
+  not only what failed.
+- **Composable.** Four orchestration strategies, four model backends, and
+  diff / repo inputs are chosen per run -- mix and match.
+
+## Install
+
+```bash
+pip install codejury                 # core + CLI
+pip install 'codejury[anthropic]'    # the provider you'll use: anthropic | openai | litellm
+```
+
+## Quickstart
+
+```bash
+# No API key needed -- prove the pipeline runs end to end with mock layers
+codejury dry-run
+
+# A real audit: set a key, then review your staged changes
+export ANTHROPIC_API_KEY=sk-ant-...
+git diff | codejury audit --provider anthropic
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `codejury dry-run` | Run the mock pipeline with no key (smoke test). |
+| `codejury audit [diff]` | Audit a unified diff from a file or stdin (`-`). |
+| `codejury scan <dir>` | Audit a whole directory tree, capability by capability. |
+| `codejury run <task>` | Run a named task preset (see [Tasks](#tasks)). |
+| `codejury eval` | Score the golden cases and report precision / recall. |
+
+Shared flags: `--orchestrator {single,pipeline,debate,reflexion}`,
+`--provider {anthropic,openai,litellm}`, `--model`, `--format {text,markdown,json}`.
+
+```bash
+# Multi-round adversarial debate, rendered as Markdown
+git diff | codejury audit --orchestrator debate --format markdown - > report.md
+
+# Deep whole-repo scan, scoped to a few capabilities to bound the cost
+codejury scan ./myrepo --only secrets,input_validation,crypto
+```
+
+## Configuration
+
+Provider keys are read from the environment (codejury does **not** auto-load
+`.env` -- copy `.env.example` and `source` it):
+
+| Variable | Used by |
+|---|---|
+| `ANTHROPIC_API_KEY` | `--provider anthropic` |
+| `OPENAI_API_KEY` | `--provider openai` |
+| `CODEJURY_API_BASE` / `CODEJURY_API_KEY` / `CODEJURY_MODEL` | defaults for `--api-base` / `--api-key` / `--model` (any provider) |
+
+The `CODEJURY_*` overrides make a LiteLLM proxy a one-liner:
+
+```bash
+# with CODEJURY_API_BASE / CODEJURY_API_KEY / CODEJURY_MODEL in a sourced .env
+git diff | codejury audit --provider litellm -
+```
+
+## Tasks
+
+A task is a named preset (capabilities + orchestrator + provider + model). It
+lives in a YAML file; the API key always stays in the environment.
+
+```yaml
+# mytasks/proxy_scan.yaml  ->  codejury run proxy_scan --tasks mytasks
+name: proxy_scan
+orchestrator: debate
+provider: litellm
+model: your-alias
+api_base: https://litellm.example.com   # key from CODEJURY_API_KEY
+capabilities: [authn, input_validation, secrets]   # omit to check all
+```
+
+## Capabilities
+
+The library covers all 11 OWASP ASVS areas, one YAML each under
+`codejury/data/capabilities/`. These ids are what `--only` and a task's
+`capabilities:` accept:
+
+`authn` · `authz` · `session` · `input_validation` · `output_encoding` ·
+`crypto` · `secrets` · `data_protection` · `error_logging` ·
+`business_logic` · `dependency_config`
+
+To tune for your codebase, edit these files (add patterns / sharpen wording) --
+no code change needed.
+
+## Architecture
+
+```
+Layer 5  Task            preset: source + capabilities + orchestrator + agents
+Layer 4  Capability      YAML domain knowledge (authn / authz / ...)
+Layer 3  Orchestrator    strategy (single / pipeline / debate / reflexion)
+         Source          input (diff / repo / function)
+         Agent           role (finder / challenger / judge / verifier)
+Layer 2  Provider        model backend (anthropic / openai / litellm / mock)
+Layer 1  Infrastructure  cross-cutting utilities (json parsing, retry, ...)
+```
+
+Layers talk only through typed data, and each is an abstract base class plus
+implementations, so the axes (task / orchestration / model / input) compose
+independently.
+
+## Limitations
+
+- **Prompts are a first pass.** Expect false positives and misses on real code.
+  Tune by editing the capability YAML and growing the golden set; measure the
+  effect with `codejury eval`.
+- **Local-pattern checks are sharper than data-flow ones.** Capabilities judged
+  from one spot (weak crypto, hardcoded secrets) are reliable; taint / data-flow
+  ones like path traversal over-flag in single-file review because the verifier
+  can't see whether a value is attacker-controlled. `scan --callers` adds
+  cross-file call sites for provenance (helps some cases, not a full fix); also
+  scope with `--only` or challenge findings with `--orchestrator debate`.
+- **`scan` cost scales as files x capabilities.** It is a periodic deep audit,
+  not a quick check -- scope it with `--only`. Day to day, audit the diff.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

{codejury-0.2.0 → codejury-0.4.0}/codejury/agents/verifier.py

@@ -44,7 +44,7 @@ class VerifierAgent(Agent):
     def run(self, ctx: AnalysisContext) -> list[Observation]:
         verdicts: list[Observation] = []
         for cap in ctx.capabilities:
-            prompt = _build_prompt(ctx.artifact.path, ctx.artifact.content, cap)
+            prompt = _build_prompt(ctx.artifact.path, ctx.artifact.content, cap, ctx.artifact.context)
             result = self._provider.complete(
                 system=_SYSTEM,
                 messages=[Message(role="user", content=prompt)],
@@ -70,14 +70,25 @@ def _render_capability(cap: Capability) -> str:
     return "\n".join(lines)
 
 
-def _build_prompt(path: str, content: str, cap: Capability) -> str:
+def _build_prompt(path: str, content: str, cap: Capability, context: str = "") -> str:
     sub_names = ", ".join(cap.sub_capabilities) or "(none)"
+    context_block = (
+        f"Related code (call sites / usages elsewhere -- for tracing where values come from, "
+        f"NOT under review):\n```\n{context}\n```\n\n"
+        if context
+        else ""
+    )
     return (
         "Check the code below against this capability.\n\n"
         f"{_render_capability(cap)}\n\n"
         f"Code under review ({path}):\n```\n{content}\n```\n\n"
+        f"{context_block}"
         f"For EVERY sub_capability ({sub_names}) output one verdict, even if SECURE "
-        "or NOT_PRESENT. Cite matched pattern ids and evidence lines.\n\n"
+        "or NOT_PRESENT. Cite matched pattern ids and evidence lines.\n"
+        "For input-driven issues (injection, path traversal, SSRF), mark VULNERABLE only when "
+        "untrusted/external input could plausibly reach the sink in the code shown. A constant, "
+        "a stored data field, a value from trusted config, or a path or argument the operator "
+        "supplies (e.g. a CLI argument) is not attacker-controlled -- do not flag it.\n\n"
         "Respond with a single JSON object exactly like:\n" + _JSON_SHAPE
     )
 

{codejury-0.2.0 → codejury-0.4.0}/codejury/assembly.py

@@ -11,6 +11,7 @@ import os
 from codejury.agents.base import Agent
 from codejury.agents.debate import ChallengerAgent, FinderAgent, JudgeAgent
 from codejury.agents.verifier import VerifierAgent
+from codejury.domain.artifact import CodeArtifact
 from codejury.domain.capability import Capability
 from codejury.domain.context import AnalysisContext
 from codejury.domain.result import AnalysisResult
@@ -66,15 +67,24 @@ def build_orchestration(
     return verifier, SingleOrchestrator()
 
 
-def run_over_source(
-    source: Source,
+def run_over_artifacts(
+    artifacts: list[CodeArtifact],
     capabilities: list[Capability],
     agents: dict[str, Agent],
     orchestrator: Orchestrator,
 ) -> list[tuple[str, AnalysisResult]]:
     """Run the orchestration over each artifact, returning (path, result) per artifact."""
     results = []
-    for artifact in source.list_artifacts():
+    for artifact in artifacts:
         ctx = AnalysisContext(artifact=artifact, capabilities=capabilities)
         results.append((artifact.path, orchestrator.run(agents, ctx)))
     return results
+
+
+def run_over_source(
+    source: Source,
+    capabilities: list[Capability],
+    agents: dict[str, Agent],
+    orchestrator: Orchestrator,
+) -> list[tuple[str, AnalysisResult]]:
+    return run_over_artifacts(source.list_artifacts(), capabilities, agents, orchestrator)

{codejury-0.2.0 → codejury-0.4.0}/codejury/cli.py

@@ -20,6 +20,7 @@ from codejury.assembly import (
     STRATEGIES,
     build_orchestration,
     make_provider,
+    run_over_artifacts,
     run_over_source,
 )
 from codejury.domain.artifact import CodeArtifact
@@ -33,7 +34,9 @@ from codejury.providers.base import Provider
 from codejury.providers.mock import MockProvider
 from codejury.reporting import to_json, to_markdown
 from codejury.resources import CAPABILITIES_DIR, GOLDEN_DIR, TASKS_DIR
+from codejury.sources.chunker import Chunker
 from codejury.sources.diff import DiffSource
+from codejury.sources.repo import RepoSource
 from codejury.tasks.base import run_task
 from codejury.tasks.registry import load_tasks
 
@@ -69,6 +72,32 @@ def audit(
     return run_over_source(DiffSource(diff_text), capabilities, agents, orchestrator)
 
 
+def scan(
+    directory: str,
+    capabilities: list[Capability],
+    *,
+    provider: Provider,
+    model: str,
+    max_tokens: int = 2048,
+    strategy: str = "pipeline",
+    extensions: tuple[str, ...] = (".py",),
+    max_chars: int = 200_000,
+    with_callers: bool = False,
+) -> list[tuple[str, AnalysisResult]]:
+    """Audit every matching file in a directory tree, returning (path, result) per artifact."""
+    source = RepoSource(
+        directory, extensions=extensions, chunker=Chunker(max_chars=max_chars), with_callers=with_callers
+    )
+    artifacts = source.list_artifacts()
+    calls = len(artifacts) * len(capabilities)
+    print(
+        f"scanning {len(artifacts)} artifacts x {len(capabilities)} capabilities (~{calls} model calls)",
+        file=sys.stderr,
+    )
+    agents, orchestrator = build_orchestration(strategy, provider=provider, model=model, max_tokens=max_tokens)
+    return run_over_artifacts(artifacts, capabilities, agents, orchestrator)
+
+
 def _render_dry_run(result: AnalysisResult) -> str:
     lines = [f"observations: {len(result.observations)}"]
     for o in result.observations:
@@ -140,6 +169,23 @@ def main(argv: list[str] | None = None) -> int:
     audit_p.add_argument("--api-base", default=DEFAULT_API_BASE, help="provider base URL (env: CODEJURY_API_BASE)")
     audit_p.add_argument("--api-key", default=DEFAULT_API_KEY, help="provider API key (env: CODEJURY_API_KEY)")
 
+    scan_p = sub.add_parser("scan", help="audit a whole directory tree (deep, capability by capability)")
+    scan_p.add_argument("directory", help="directory to scan")
+    scan_p.add_argument("--ext", default=".py", help="comma-separated file extensions (default .py)")
+    scan_p.add_argument("--only", default=None, help="comma-separated capability ids to scan (default: all)")
+    scan_p.add_argument("--capabilities", default=CAPABILITIES_DIR, help="capability YAML directory")
+    scan_p.add_argument("--orchestrator", choices=STRATEGIES, default="pipeline")
+    scan_p.add_argument("--provider", choices=PROVIDERS, default="anthropic")
+    scan_p.add_argument("--format", choices=_FORMATS, default="text", dest="fmt")
+    scan_p.add_argument("--model", default=DEFAULT_MODEL)
+    scan_p.add_argument("--max-tokens", type=int, default=2048)
+    scan_p.add_argument("--max-chars", type=int, default=200_000, help="chunk budget; default keeps whole files")
+    scan_p.add_argument(
+        "--callers", action="store_true", help="add cross-file call sites as context (cuts taint false positives)"
+    )
+    scan_p.add_argument("--api-base", default=DEFAULT_API_BASE, help="provider base URL (env: CODEJURY_API_BASE)")
+    scan_p.add_argument("--api-key", default=DEFAULT_API_KEY, help="provider API key (env: CODEJURY_API_KEY)")
+
     run_p = sub.add_parser("run", help="run a named task preset against a unified diff")
     run_p.add_argument("task", help="task name")
     run_p.add_argument("diff", nargs="?", default="-", help="unified diff file, or - for stdin")
@@ -171,6 +217,26 @@ def main(argv: list[str] | None = None) -> int:
         print(_render_results(args.fmt, results))
         return 0
 
+    if args.command == "scan":
+        capabilities = load_capabilities(args.capabilities)
+        if args.only:
+            wanted = {x.strip() for x in args.only.split(",")}
+            capabilities = [c for c in capabilities if c.id in wanted]
+        extensions = tuple(e if e.startswith(".") else "." + e for e in args.ext.split(","))
+        results = scan(
+            args.directory,
+            capabilities,
+            provider=make_provider(args.provider, api_key=args.api_key, api_base=args.api_base),
+            model=args.model,
+            max_tokens=args.max_tokens,
+            strategy=args.orchestrator,
+            extensions=extensions,
+            max_chars=args.max_chars,
+            with_callers=args.callers,
+        )
+        print(_render_results(args.fmt, results))
+        return 0
+
     if args.command == "run":
         tasks = load_tasks(args.tasks)
         if args.task not in tasks:

{codejury-0.2.0 → codejury-0.4.0}/codejury/data/capabilities/input_validation.yaml

@@ -44,13 +44,19 @@ sub_capabilities:
       - 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
+        why_ok: >-
+          Arguments are passed directly to execve, so the shell never parses input. This
+          only applies to code that actually spawns a process; an ordinary function,
+          method, or library/API call (e.g. provider.complete) is not command execution.
 
     anti_patterns:
       - id: CMDI-BAD-1
         cwe: CWE-78
         severity: CRITICAL
-        description: Invoke a shell with an interpolated command string
+        description: >-
+          Pass interpolated input to an OS shell or subprocess -- os.system, os.popen,
+          subprocess(..., shell=True), or eval/exec. A normal function, method, or
+          library/API call is NOT this; flag only an actual shell or process invocation.
         signals: ["os.system(", "shell=True", "os.popen("]
         why_bad: Shell metacharacters in input let an attacker run arbitrary commands
         example_bad: |
@@ -72,15 +78,28 @@ sub_capabilities:
         signals: ["os.path.realpath", "Path(...).resolve()", "is_relative_to("]
         why_ok: A resolved path outside the base is rejected before any file access
 
+      - id: PATH-OK-2
+        description: >-
+          Use a path that is not attacker-controlled -- a data field, a directory read from
+          trusted config, or a path the operator passes on the command line
+        why_ok: >-
+          Traversal needs an external attacker to control the path. A path stored as a
+          field, a trusted/configured directory, or an operator-supplied CLI argument is
+          not a finding; neither is merely declaring a `path` attribute.
+
     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
+        description: >-
+          Take an externally controlled value (HTTP request, upload, form, query, or message
+          field) and use it in a filesystem open/read/write without resolving it and confirming
+          it stays in an allowed base. NOT this: a path kept as a data field, a directory from
+          trusted config, or a path the operator passes on the CLI.
+        signals: ["request.", "upload", "filename", "os.path.join("]
+        why_bad: Sequences like ../ let attacker input escape the intended directory
         example_bad: |
-          open(os.path.join(UPLOAD_DIR, filename))
+          open(os.path.join(UPLOAD_DIR, request.args["filename"]))
         example_good: |
           target = (UPLOAD_DIR / filename).resolve()
           if not target.is_relative_to(UPLOAD_DIR):

codejury-0.4.0/codejury/data/capabilities/secrets.yaml

@@ -0,0 +1,72 @@
+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: >-
+          A variable that reads its value from the environment or a secret manager is the
+          correct pattern, not a violation -- nothing secret is written in the source.
+
+      - id: SEC-OK-2
+        description: Receive a secret as a function or constructor parameter (dependency injection)
+        signals: ["def __init__(self, *, api_key", "api_key: str | None = None", "api_key=api_key"]
+        why_ok: >-
+          Accepting or forwarding a key through a parameter or variable is correct -- the value
+          comes from the caller or the environment, not a literal in the source. Only an actual
+          key string written in the code is a finding.
+
+    anti_patterns:
+      - id: SEC-BAD-1
+        cwe: CWE-798
+        severity: HIGH
+        description: >-
+          Assign a literal credential string -- an actual key/token value written in the source.
+          A variable, parameter, env lookup, or a non-credential string (e.g. a model name or
+          URL) that merely holds or forwards a value is NOT this.
+        signals: ['api_key = "sk', 'token = "ghp_', 'aws_secret_access_key = "']
+        why_bad: The credential leaks with the source and cannot be rotated easily
+        example_bad: |
+          API_KEY = "sk_live_51HxQ....actual-secret-value"   # literal secret in source
+        example_good: |
+          api_key = os.environ["API_KEY"]                    # read from env -- fine
+          client = Client(api_key=api_key)                   # passed as a parameter -- fine
+
+      - id: SEC-BAD-2
+        cwe: CWE-259
+        severity: HIGH
+        description: Assign a literal password string in source
+        signals: ['password = "', 'passwd = "']
+        why_bad: A fixed password in code is shared, discoverable, and unchangeable
+
+  exposure:
+    correct_patterns:
+      - id: SEC-OK-3
+        description: Log or render only non-credential data, or redact secrets before logging
+        why_ok: >-
+          Emitting analysis results, status, or non-secret fields is fine. The risk is logging
+          the value of a credential, not handling data in general.
+
+    anti_patterns:
+      - id: SEC-BAD-3
+        cwe: CWE-532
+        severity: MEDIUM
+        description: Write the value of a secret, token, or password to logs or output
+        signals: ["log.info(token", "print(password", "logger.debug(secret", "log.info(api_key"]
+        why_bad: Logs are widely accessible and long-lived, so a logged secret value spreads
+
+      - 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:
+  - a literal string assigned to a key, token, password, secret, or credential name
+  - imports of a secret manager or vault client
+  - .env or config files with credential-looking values

{codejury-0.2.0 → codejury-0.4.0}/codejury/domain/artifact.py

@@ -18,3 +18,6 @@ class CodeArtifact:
     kind: ArtifactKind
     path: str       # identifier used when building Evidence references
     content: str    # the diff/file/function text the agent analyzes
+    # related code (e.g. cross-file call sites) shown to help trace data flow,
+    # but not itself under review
+    context: str = ""

codejury-0.4.0/codejury/sources/callers.py

@@ -0,0 +1,46 @@
+"""Lightweight cross-file caller context.
+
+For a file under review, find where the functions and classes it defines are
+called elsewhere in the repository. Showing those call sites lets the verifier
+trace where an argument comes from -- which is exactly what single-file review
+lacks for taint-style issues (a path/command that is operator-supplied vs
+attacker-controlled). This is a textual usage finder, not a full call graph.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+
+
+def defined_names(content: str) -> set[str]:
+    """Top-level function and class names defined in `content`."""
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return set()
+    return {
+        node.name
+        for node in tree.body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+    }
+
+
+def caller_context(target_path: str, files: dict[str, str], *, max_lines: int = 30) -> str:
+    """Lines elsewhere in `files` that call the names defined in `target_path`."""
+    names = defined_names(files.get(target_path, ""))
+    if not names:
+        return ""
+    # word-boundary call: `name(` not preceded/followed by other identifier chars
+    call = re.compile(r"\b(?:" + "|".join(re.escape(n) for n in names) + r")\s*\(")
+
+    hits: list[str] = []
+    for path in sorted(files):
+        if path == target_path:
+            continue
+        for lineno, line in enumerate(files[path].splitlines(), 1):
+            if call.search(line):
+                hits.append(f"{path}:{lineno}: {line.strip()}")
+                if len(hits) >= max_lines:
+                    return "\n".join(hits)
+    return "\n".join(hits)