codejury 0.2.0__tar.gz → 0.3.0__tar.gz

codejury-0.3.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: codejury
+Version: 0.3.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`.
+- **`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.3.0/README.md

@@ -0,0 +1,137 @@
+# 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`.
+- **`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.3.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.3.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,29 @@ 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 = 8000,
+) -> 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))
+    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 +166,20 @@ 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=8000, help="chunk budget for large files")
+    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 +211,25 @@ 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,
+        )
+        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.3.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.3.0/codejury.egg-info/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: codejury
+Version: 0.3.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`.
+- **`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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codejury"
-version = "0.2.0"
+version = "0.3.0"
 description = "General-purpose Application Security AI audit framework -- five-layer architecture, capabilities as first-class data"
 readme = "README.md"
 requires-python = ">=3.12"