codejury 1.0.1__tar.gz → 1.2.0__tar.gz

{codejury-1.0.1 → codejury-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codejury
-Version: 1.0.1
+Version: 1.2.0
 Summary: AI-assisted security review for code diffs and whole repositories.
 Author: AISecLabs
 License-Expression: MIT
@@ -14,6 +14,8 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -30,6 +32,9 @@ Provides-Extra: all
 Requires-Dist: anthropic>=0.40; extra == "all"
 Requires-Dist: openai>=1.0; extra == "all"
 Requires-Dist: litellm>=1.0; extra == "all"
+Provides-Extra: evm
+Requires-Dist: slither-analyzer>=0.10; extra == "evm"
+Requires-Dist: web3>=6.0; extra == "evm"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: jsonschema>=4.0; extra == "dev"
@@ -44,9 +49,10 @@ Dynamic: license-file
  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚════╝  ╚═════╝ ╚═╝  ╚═╝   ╚═╝
 ```
 
+[![Tests](https://img.shields.io/github/actions/workflow/status/aiseclabs/codejury/test.yml?label=tests)](https://github.com/aiseclabs/codejury/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/codejury)](https://pypi.org/project/codejury/)
 [![Python](https://img.shields.io/pypi/pyversions/codejury)](https://pypi.org/project/codejury/)
-[![License: MIT](https://img.shields.io/pypi/l/codejury)](https://github.com/aiseclabs/codejury/blob/master/LICENSE)
+[![License: MIT](https://img.shields.io/pypi/l/codejury)](https://github.com/aiseclabs/codejury/blob/main/LICENSE)
 
 AI-assisted security review for code diffs and whole repositories.
 
@@ -57,8 +63,10 @@ The tool has two review paths:
   candidates, verifies findings, and checks coverage with a gate.
 
 Security knowledge is data. Vulnerability classes, language guides, framework guides, and
-protocol guides live in markdown under `codejury/knowledge/`, so adding a stack or class is
-usually a data change rather than a Python code change.
+protocol guides live in markdown under each review domain's `knowledge/` directory, for
+example `codejury/domains/web/knowledge/`, so adding a stack or class is usually a data
+change rather than a Python code change. The `web` domain is the default and `evm` reviews
+Solidity smart contracts, selected with `--domain` or detected automatically.
 
 ## Install
 
@@ -84,11 +92,41 @@ directory. Pass `--dir` to install it somewhere else.
 Set a provider key through flags or environment variables:
 
 ```bash
+export CODEJURY_MODEL=claude-opus-4-8
 export CODEJURY_API_KEY=...
-export CODEJURY_MODEL=claude-sonnet-4-6
 export CODEJURY_API_BASE=...   # optional gateway or proxy
 ```
 
+Both review paths name three model roles, finder, challenger, and judge. The finder finds, the
+challenger refutes, the judge confirms before a deletion. Each role defaults to the base
+`--model`, so a single-model run sets only `--model`. Put a different vendor in any seat for
+cross-model review, where uncorrelated blind spots catch what one model misses, and a deletion
+needs the judge to be a distinct model from the challenger so no lone skeptic drops a real
+finding. With the judge not distinct, nothing is refuted, the recall-safe default.
+
+Each role takes a full backend, the same five fields as the base, every one unset by default:
+`CODEJURY_<ROLE>_PROVIDER`, `_MODEL`, `_API_KEY`, `_API_BASE`, `_WIRE_API`, with `<ROLE>` one of
+`FINDER`, `CHALLENGER`, `JUDGE`, and the matching `--<role>-provider`, `--<role>-model`,
+`--<role>-api-key`, `--<role>-api-base`, `--<role>-wire-api` flags. An unset field inherits the
+base, so you set none of these for a single-model run and override only the seat you want to
+change. The key and the api-base inherit the base only when the role keeps the base provider. A
+role that switches vendor brings its own key, since the base key belongs to the base vendor. For
+example a Claude base finder challenged by GPT and confirmed by Claude:
+
+```bash
+export CODEJURY_CHALLENGER_PROVIDER=openai
+export CODEJURY_CHALLENGER_MODEL=...         # a GPT model, the skeptic
+export CODEJURY_CHALLENGER_API_KEY=...
+export CODEJURY_CHALLENGER_WIRE_API=responses   # the gpt-5 reasoning models speak Responses
+export CODEJURY_JUDGE_MODEL=...              # a Claude model, the confirmer, distinct from the challenger
+```
+
+The same `CODEJURY_FINDER_*` / `CODEJURY_CHALLENGER_*` / `CODEJURY_JUDGE_*` and the matching
+`--finder-* / --challenger-* / --judge-*` flags work on both `review diff` and `review repo`.
+Note that `review repo --run` finds with one model, the finder, it no longer adds a second
+co-finder, and a seat that runs on the subscription supplies its own review, so it ignores
+that seat's backend flags while the others still apply.
+
 The tool does not auto-load `.env`.
 
 Useful flags:
@@ -98,21 +136,28 @@ Useful flags:
 - `--api-key <key>`
 - `--api-base <url>`
 - `--retries <n>`
+- `--timeout <seconds>`
 
 ## Data Boundary
 
 The tool sends code-derived content to the model provider you configure, so know what
 leaves the machine before reviewing a proprietary repository:
 
-- Diff Review sends the unified diff under review.
-- Repo Review with `--reviewer model` sends bounded source snippets, the detected stack
+- Diff Review on the `api` row sends the unified diff under review. On the `subscription`
+  row it sends the diff in the `claude -p` prompt through your Claude Code account, and the
+  diff agent uses no file tools, so only the diff text leaves the machine, not local files.
+- Under the default `--executor auto`, each seat follows the `api` row when it has a key
+  and the `subscription` row when it falls back to your Claude Code subscription, so what
+  leaves the machine is decided per seat by whether that seat has a key.
+- Repo Review with `--executor api` sends bounded source snippets, the detected stack
   notes, the vulnerability guidance, and the findings.
-- Verification with `--reviewer model` sends the cited source file and the finding
-  details. With `--reviewer claude-cli`, Claude Code receives the finding details and
-  reads the code itself through its read-only tools.
-- `--reviewer claude-cli` does not use the configured provider key. It runs Claude Code
-  with read-only file tools, and Claude Code may send prompts and the code it reads
-  through your Claude Code account, so the code does not stay local.
+- Verification with `--executor api` sends the cited source file and the finding
+  details. On the `subscription` row, Claude Code receives the finding details and reads
+  the code itself through its read-only tools.
+- A repo seat on the `subscription` row does not use the configured provider key. It runs
+  Claude Code with read-only file tools, and Claude Code may send prompts and the code it
+  reads through your Claude Code account, so the code does not stay local. The diff agent is
+  narrower, it reads no files and sees only the diff in the prompt.
 
 A custom `--api-base` or a LiteLLM proxy becomes part of the trust boundary, so the data
 above also reaches that gateway. Prefer the `CODEJURY_API_KEY` environment variable over
@@ -126,22 +171,34 @@ Diff Review is the fast coded path. It audits a unified diff with either a stand
 single model call or an adversarial Finder, Challenger, and Judge pass.
 
 ```bash
-# Review a diff file
+# review a diff file
 codejury review diff --file changes.diff
 
-# Review a git range
+# review a git range
 codejury review diff --repo /path/to/app --git-range origin/main...HEAD
 
-# Review stdin
+# review stdin
 git diff HEAD~1 | codejury review diff
 
-# Use adversarial mode for extra recall on subtle cross-file logic
+# use adversarial mode for extra recall on subtle cross-file logic
 codejury review diff --file changes.diff --mode adversarial
 
-# Emit SARIF and fail on HIGH or CRITICAL findings
+# emit SARIF and fail on HIGH or CRITICAL findings
 codejury review diff --file changes.diff --format sarif --fail-on high
+
+# review with no provider key, riding your Claude Code subscription
+codejury review diff --file changes.diff --executor subscription
+
+# adversarial with a keyless Claude finder and judge plus an OpenAI challenger on its own key
+codejury review diff --file changes.diff --mode adversarial \
+  --challenger-provider openai --challenger-api-key "$OPENAI_API_KEY"
 ```
 
+Diff Review takes the same `--executor auto|api|subscription` as Repo Review, see Review
+Strategy. The default `auto` calls the provider when a seat has a key and falls back to your
+Claude Code subscription for a keyless Anthropic seat. Unlike the repo agent, the diff agent
+answers from the diff in the prompt and reads no files.
+
 `codejury review diff --dry-run` uses a mock provider and a built-in demo diff, so it needs
 no API key.
 
@@ -200,18 +257,46 @@ For a headless run, use:
 codejury review repo /path/to/repo --run
 ```
 
-Use `--reviewer claude-cli` only when you want the Claude Code backend to run unit reviews
-and verification through local Claude CLI access.
+### Review Strategy
+
+A `--run` chooses how each unit is reviewed:
+
+- `--executor auto` is the default. Each seat, the finder and the skeptic, calls the
+  provider when it has a reachable key and falls back to a headless `claude -p`
+  subscription agent for a keyless Anthropic seat, so a keyless run works with no provider
+  key. A keyless non-Anthropic seat, such as an OpenAI finder with no key, is a loud error,
+  it has no subscription to fall back to. This is what lets a Claude finder ride your
+  subscription while an OpenAI challenger uses its own key.
+- `--executor api` makes one grounded model call per unit and requires a key, a missing key
+  is a loud startup error, the same point as auto. Add `--facts` to ground that call in a
+  tool-extracted call graph, storage layout, and read and write sets when the domain binds a
+  facts backend, such as the EVM Slither backend. This is what gives a smart contract review
+  its call relationships, so prefer `--run --facts` on Solidity.
+- `--executor subscription` always runs each unit and its verification as a headless
+  `claude -p` agent that reads and traces the files itself with read-only tools, using your
+  Claude Code access and no provider key. Use it when you want a tool-using agent rather
+  than a single grounded call even where a key is present.
+
+Set a distinct `--judge-model`, the confirmer, from the challenger to enable cross-model
+verification. The challenger refutes a finding and the judge must agree before it is dropped,
+so a deletion needs two models. With the judge not distinct from the challenger, the verify
+stage refutes nothing, the recall-safe default.
 
 ## Supported Knowledge
 
-Current guide coverage includes:
+The tool selects a review domain with `--domain`, `auto` by default. The `web` domain is
+the default for application code. The `evm` domain reviews Solidity smart contracts for
+classes such as reentrancy, access control, oracle manipulation, accounting precision, and
+signature replay.
+
+Current guide coverage in the web domain includes:
 
 - Python: Django, Flask, FastAPI, Celery
 - Go: Gin, Echo
 - JavaScript and TypeScript: Express, NestJS
 - Protocols: OAuth and OIDC
 
+The evm domain ships a Solidity guide and the smart contract vulnerability classes above.
 Unguided stacks still work, but the agent relies more on general methodology and model
 knowledge.
 
@@ -255,13 +340,13 @@ uploads SARIF to code scanning, and fails on HIGH or CRITICAL findings.
 Add security knowledge as markdown:
 
 - Vulnerability class:
-  `codejury/knowledge/vulnerabilities/<id>.md`
+  `codejury/domains/<domain>/knowledge/vulnerabilities/<id>.md`
 - Language guide:
-  `codejury/knowledge/guides/languages/<language>.md`
+  `codejury/domains/<domain>/knowledge/guides/languages/<language>.md`
 - Framework guide:
-  `codejury/knowledge/guides/frameworks/<language>/<framework>.md`
+  `codejury/domains/<domain>/knowledge/guides/frameworks/<language>/<framework>.md`
 - Protocol guide:
-  `codejury/knowledge/guides/protocols/<protocol>.md`
+  `codejury/domains/<domain>/knowledge/guides/protocols/<protocol>.md`
 
 Keep frontmatter and detection signals data-driven. Avoid adding language, framework, or
 vulnerability-specific detection logic to Python unless the engine itself needs a generic

{codejury-1.0.1 → codejury-1.2.0}/README.md

@@ -7,9 +7,10 @@
  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚════╝  ╚═════╝ ╚═╝  ╚═╝   ╚═╝
 ```
 
+[![Tests](https://img.shields.io/github/actions/workflow/status/aiseclabs/codejury/test.yml?label=tests)](https://github.com/aiseclabs/codejury/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/codejury)](https://pypi.org/project/codejury/)
 [![Python](https://img.shields.io/pypi/pyversions/codejury)](https://pypi.org/project/codejury/)
-[![License: MIT](https://img.shields.io/pypi/l/codejury)](https://github.com/aiseclabs/codejury/blob/master/LICENSE)
+[![License: MIT](https://img.shields.io/pypi/l/codejury)](https://github.com/aiseclabs/codejury/blob/main/LICENSE)
 
 AI-assisted security review for code diffs and whole repositories.
 
@@ -20,8 +21,10 @@ The tool has two review paths:
   candidates, verifies findings, and checks coverage with a gate.
 
 Security knowledge is data. Vulnerability classes, language guides, framework guides, and
-protocol guides live in markdown under `codejury/knowledge/`, so adding a stack or class is
-usually a data change rather than a Python code change.
+protocol guides live in markdown under each review domain's `knowledge/` directory, for
+example `codejury/domains/web/knowledge/`, so adding a stack or class is usually a data
+change rather than a Python code change. The `web` domain is the default and `evm` reviews
+Solidity smart contracts, selected with `--domain` or detected automatically.
 
 ## Install
 
@@ -47,11 +50,41 @@ directory. Pass `--dir` to install it somewhere else.
 Set a provider key through flags or environment variables:
 
 ```bash
+export CODEJURY_MODEL=claude-opus-4-8
 export CODEJURY_API_KEY=...
-export CODEJURY_MODEL=claude-sonnet-4-6
 export CODEJURY_API_BASE=...   # optional gateway or proxy
 ```
 
+Both review paths name three model roles, finder, challenger, and judge. The finder finds, the
+challenger refutes, the judge confirms before a deletion. Each role defaults to the base
+`--model`, so a single-model run sets only `--model`. Put a different vendor in any seat for
+cross-model review, where uncorrelated blind spots catch what one model misses, and a deletion
+needs the judge to be a distinct model from the challenger so no lone skeptic drops a real
+finding. With the judge not distinct, nothing is refuted, the recall-safe default.
+
+Each role takes a full backend, the same five fields as the base, every one unset by default:
+`CODEJURY_<ROLE>_PROVIDER`, `_MODEL`, `_API_KEY`, `_API_BASE`, `_WIRE_API`, with `<ROLE>` one of
+`FINDER`, `CHALLENGER`, `JUDGE`, and the matching `--<role>-provider`, `--<role>-model`,
+`--<role>-api-key`, `--<role>-api-base`, `--<role>-wire-api` flags. An unset field inherits the
+base, so you set none of these for a single-model run and override only the seat you want to
+change. The key and the api-base inherit the base only when the role keeps the base provider. A
+role that switches vendor brings its own key, since the base key belongs to the base vendor. For
+example a Claude base finder challenged by GPT and confirmed by Claude:
+
+```bash
+export CODEJURY_CHALLENGER_PROVIDER=openai
+export CODEJURY_CHALLENGER_MODEL=...         # a GPT model, the skeptic
+export CODEJURY_CHALLENGER_API_KEY=...
+export CODEJURY_CHALLENGER_WIRE_API=responses   # the gpt-5 reasoning models speak Responses
+export CODEJURY_JUDGE_MODEL=...              # a Claude model, the confirmer, distinct from the challenger
+```
+
+The same `CODEJURY_FINDER_*` / `CODEJURY_CHALLENGER_*` / `CODEJURY_JUDGE_*` and the matching
+`--finder-* / --challenger-* / --judge-*` flags work on both `review diff` and `review repo`.
+Note that `review repo --run` finds with one model, the finder, it no longer adds a second
+co-finder, and a seat that runs on the subscription supplies its own review, so it ignores
+that seat's backend flags while the others still apply.
+
 The tool does not auto-load `.env`.
 
 Useful flags:
@@ -61,21 +94,28 @@ Useful flags:
 - `--api-key <key>`
 - `--api-base <url>`
 - `--retries <n>`
+- `--timeout <seconds>`
 
 ## Data Boundary
 
 The tool sends code-derived content to the model provider you configure, so know what
 leaves the machine before reviewing a proprietary repository:
 
-- Diff Review sends the unified diff under review.
-- Repo Review with `--reviewer model` sends bounded source snippets, the detected stack
+- Diff Review on the `api` row sends the unified diff under review. On the `subscription`
+  row it sends the diff in the `claude -p` prompt through your Claude Code account, and the
+  diff agent uses no file tools, so only the diff text leaves the machine, not local files.
+- Under the default `--executor auto`, each seat follows the `api` row when it has a key
+  and the `subscription` row when it falls back to your Claude Code subscription, so what
+  leaves the machine is decided per seat by whether that seat has a key.
+- Repo Review with `--executor api` sends bounded source snippets, the detected stack
   notes, the vulnerability guidance, and the findings.
-- Verification with `--reviewer model` sends the cited source file and the finding
-  details. With `--reviewer claude-cli`, Claude Code receives the finding details and
-  reads the code itself through its read-only tools.
-- `--reviewer claude-cli` does not use the configured provider key. It runs Claude Code
-  with read-only file tools, and Claude Code may send prompts and the code it reads
-  through your Claude Code account, so the code does not stay local.
+- Verification with `--executor api` sends the cited source file and the finding
+  details. On the `subscription` row, Claude Code receives the finding details and reads
+  the code itself through its read-only tools.
+- A repo seat on the `subscription` row does not use the configured provider key. It runs
+  Claude Code with read-only file tools, and Claude Code may send prompts and the code it
+  reads through your Claude Code account, so the code does not stay local. The diff agent is
+  narrower, it reads no files and sees only the diff in the prompt.
 
 A custom `--api-base` or a LiteLLM proxy becomes part of the trust boundary, so the data
 above also reaches that gateway. Prefer the `CODEJURY_API_KEY` environment variable over
@@ -89,22 +129,34 @@ Diff Review is the fast coded path. It audits a unified diff with either a stand
 single model call or an adversarial Finder, Challenger, and Judge pass.
 
 ```bash
-# Review a diff file
+# review a diff file
 codejury review diff --file changes.diff
 
-# Review a git range
+# review a git range
 codejury review diff --repo /path/to/app --git-range origin/main...HEAD
 
-# Review stdin
+# review stdin
 git diff HEAD~1 | codejury review diff
 
-# Use adversarial mode for extra recall on subtle cross-file logic
+# use adversarial mode for extra recall on subtle cross-file logic
 codejury review diff --file changes.diff --mode adversarial
 
-# Emit SARIF and fail on HIGH or CRITICAL findings
+# emit SARIF and fail on HIGH or CRITICAL findings
 codejury review diff --file changes.diff --format sarif --fail-on high
+
+# review with no provider key, riding your Claude Code subscription
+codejury review diff --file changes.diff --executor subscription
+
+# adversarial with a keyless Claude finder and judge plus an OpenAI challenger on its own key
+codejury review diff --file changes.diff --mode adversarial \
+  --challenger-provider openai --challenger-api-key "$OPENAI_API_KEY"
 ```
 
+Diff Review takes the same `--executor auto|api|subscription` as Repo Review, see Review
+Strategy. The default `auto` calls the provider when a seat has a key and falls back to your
+Claude Code subscription for a keyless Anthropic seat. Unlike the repo agent, the diff agent
+answers from the diff in the prompt and reads no files.
+
 `codejury review diff --dry-run` uses a mock provider and a built-in demo diff, so it needs
 no API key.
 
@@ -163,18 +215,46 @@ For a headless run, use:
 codejury review repo /path/to/repo --run
 ```
 
-Use `--reviewer claude-cli` only when you want the Claude Code backend to run unit reviews
-and verification through local Claude CLI access.
+### Review Strategy
+
+A `--run` chooses how each unit is reviewed:
+
+- `--executor auto` is the default. Each seat, the finder and the skeptic, calls the
+  provider when it has a reachable key and falls back to a headless `claude -p`
+  subscription agent for a keyless Anthropic seat, so a keyless run works with no provider
+  key. A keyless non-Anthropic seat, such as an OpenAI finder with no key, is a loud error,
+  it has no subscription to fall back to. This is what lets a Claude finder ride your
+  subscription while an OpenAI challenger uses its own key.
+- `--executor api` makes one grounded model call per unit and requires a key, a missing key
+  is a loud startup error, the same point as auto. Add `--facts` to ground that call in a
+  tool-extracted call graph, storage layout, and read and write sets when the domain binds a
+  facts backend, such as the EVM Slither backend. This is what gives a smart contract review
+  its call relationships, so prefer `--run --facts` on Solidity.
+- `--executor subscription` always runs each unit and its verification as a headless
+  `claude -p` agent that reads and traces the files itself with read-only tools, using your
+  Claude Code access and no provider key. Use it when you want a tool-using agent rather
+  than a single grounded call even where a key is present.
+
+Set a distinct `--judge-model`, the confirmer, from the challenger to enable cross-model
+verification. The challenger refutes a finding and the judge must agree before it is dropped,
+so a deletion needs two models. With the judge not distinct from the challenger, the verify
+stage refutes nothing, the recall-safe default.
 
 ## Supported Knowledge
 
-Current guide coverage includes:
+The tool selects a review domain with `--domain`, `auto` by default. The `web` domain is
+the default for application code. The `evm` domain reviews Solidity smart contracts for
+classes such as reentrancy, access control, oracle manipulation, accounting precision, and
+signature replay.
+
+Current guide coverage in the web domain includes:
 
 - Python: Django, Flask, FastAPI, Celery
 - Go: Gin, Echo
 - JavaScript and TypeScript: Express, NestJS
 - Protocols: OAuth and OIDC
 
+The evm domain ships a Solidity guide and the smart contract vulnerability classes above.
 Unguided stacks still work, but the agent relies more on general methodology and model
 knowledge.
 
@@ -218,13 +298,13 @@ uploads SARIF to code scanning, and fails on HIGH or CRITICAL findings.
 Add security knowledge as markdown:
 
 - Vulnerability class:
-  `codejury/knowledge/vulnerabilities/<id>.md`
+  `codejury/domains/<domain>/knowledge/vulnerabilities/<id>.md`
 - Language guide:
-  `codejury/knowledge/guides/languages/<language>.md`
+  `codejury/domains/<domain>/knowledge/guides/languages/<language>.md`
 - Framework guide:
-  `codejury/knowledge/guides/frameworks/<language>/<framework>.md`
+  `codejury/domains/<domain>/knowledge/guides/frameworks/<language>/<framework>.md`
 - Protocol guide:
-  `codejury/knowledge/guides/protocols/<protocol>.md`
+  `codejury/domains/<domain>/knowledge/guides/protocols/<protocol>.md`
 
 Keep frontmatter and detection signals data-driven. Avoid adding language, framework, or
 vulnerability-specific detection logic to Python unless the engine itself needs a generic