codejury 1.0.0__tar.gz → 1.1.0__tar.gz

{codejury-1.0.0 → codejury-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codejury
-Version: 1.0.0
+Version: 1.1.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,12 +32,15 @@ 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"
 Dynamic: license-file
 
-```
+```text
  ██████╗ ██████╗ ██████╗ ███████╗     ██╗██╗   ██╗██████╗ ██╗   ██╗
 ██╔════╝██╔═══██╗██╔══██╗██╔════╝     ██║██║   ██║██╔══██╗╚██╗ ██╔╝
 ██║     ██║   ██║██║  ██║█████╗       ██║██║   ██║██████╔╝ ╚████╔╝
@@ -44,6 +49,11 @@ 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/main/LICENSE)
+
 AI-assisted security review for code diffs and whole repositories.
 
 The tool has two review paths:
@@ -53,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
 
@@ -75,16 +87,31 @@ codejury install-slash-command --agent codex    # Codex
 `install-slash-command` copies `/codejury-review-repo` into the selected agent's command
 directory. Pass `--dir` to install it somewhere else.
 
-## Configure A Model Backend
+## Configure a Model Backend
 
 Set a provider key through flags or environment variables:
 
 ```bash
 export CODEJURY_API_KEY=...
-export CODEJURY_MODEL=claude-sonnet-4-6
+export CODEJURY_MODEL=claude-opus-4-8
 export CODEJURY_API_BASE=...   # optional gateway or proxy
 ```
 
+Repo Review uses a second, deliberately different model for two roles at once. On the recall
+side it finds alongside the main model, so the union takes whatever either catches and a
+single model's blind spot no longer caps recall. On the precision side it must agree before a
+candidate is refuted, so a deletion needs two models with uncorrelated blind spots and no lone
+skeptic drops a real finding. Point it at a cross-vendor model. With none set, both models
+collapse to one, the finder is single-model and the verify stage keeps every candidate, the
+recall-safe default.
+
+```bash
+export CODEJURY_CHECKER_PROVIDER=openai   # default
+export CODEJURY_CHECKER_MODEL=...         # a different model from CODEJURY_MODEL
+export CODEJURY_CHECKER_API_KEY=...
+export CODEJURY_CHECKER_API_BASE=...      # optional
+```
+
 The tool does not auto-load `.env`.
 
 Useful flags:
@@ -122,19 +149,19 @@ 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
 ```
 
@@ -156,12 +183,16 @@ codejury review repo /path/to/repo
 The workspace contains:
 
 ```text
-inventory/      attack surface, authorization model, candidates, severity rubric
+inventory/      attack surface, authorization model, seeded entrypoints, severity rubric
 units/          one review unit per candidate entrypoint
-issues/         issue write-ups
+candidates/     agent proposals, one write-up per candidate finding
+findings/       confirmed findings, written by finalize
 pocs/           runnable PoCs, when available
+findings.json   ranked machine-readable findings
 METHODOLOGY.md  full review process
 _stack.md       detected stack notes
+_refuted.md     refuted candidates and why
+_pocs.md        PoC reconciliation, planned versus delivered
 ```
 
 Then run the interactive slash command in Claude Code or Codex:
@@ -181,9 +212,10 @@ codejury review repo /path/to/repo --finalize
 codejury review repo /path/to/repo --gate
 ```
 
-`--finalize` deduplicates issue files, verifies survivors, records refuted candidates in
-`_refuted.md`, and writes ranked `findings.json`. `--gate` fails until the workspace has
-an enumerated surface, reviewed units, and calibrated findings.
+`--finalize` deduplicates candidate files, verifies survivors, writes the confirmed
+`findings/`, records refuted candidates in `_refuted.md` and PoC reconciliation in
+`_pocs.md`, and writes ranked `findings.json`. `--gate` fails until the workspace has an
+enumerated surface, reviewed units, and calibrated candidates.
 
 For a headless run, use:
 
@@ -191,18 +223,40 @@ 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:
+
+- `--reviewer model` is the default. It makes one grounded model call per unit. 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.
+- `--reviewer claude-cli` 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.
+
+Add `--checker-model`, a different model from `--model`, to enable cross-model
+verification. It finds alongside the main model on the recall side and must agree before a
+finding is dropped on the precision side. With none set, 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.
 
@@ -221,7 +275,7 @@ The tool is intentionally scoped to real exploitable application security issues
 not report dependency CVEs, style notes, generic best practices, speculation, or risks that
 only matter if production configuration leaks.
 
-## Model And Mode Guidance
+## Model and Mode Guidance
 
 Detection quality is dominated by model quality first, then mode.
 
@@ -241,18 +295,18 @@ cp examples/codejury-pr-review.yml .github/workflows/codejury-pr-review.yml
 Add `CODEJURY_API_KEY` as a repository secret. The workflow reviews the pull request diff,
 uploads SARIF to code scanning, and fails on HIGH or CRITICAL findings.
 
-## Extend The Knowledge
+## Extend the Knowledge
 
 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.0 → codejury-1.1.0}/README.md

@@ -1,4 +1,4 @@
-```
+```text
  ██████╗ ██████╗ ██████╗ ███████╗     ██╗██╗   ██╗██████╗ ██╗   ██╗
 ██╔════╝██╔═══██╗██╔══██╗██╔════╝     ██║██║   ██║██╔══██╗╚██╗ ██╔╝
 ██║     ██║   ██║██║  ██║█████╗       ██║██║   ██║██████╔╝ ╚████╔╝
@@ -7,6 +7,11 @@
  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚════╝  ╚═════╝ ╚═╝  ╚═╝   ╚═╝
 ```
 
+[![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/main/LICENSE)
+
 AI-assisted security review for code diffs and whole repositories.
 
 The tool has two review paths:
@@ -16,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
 
@@ -38,16 +45,31 @@ codejury install-slash-command --agent codex    # Codex
 `install-slash-command` copies `/codejury-review-repo` into the selected agent's command
 directory. Pass `--dir` to install it somewhere else.
 
-## Configure A Model Backend
+## Configure a Model Backend
 
 Set a provider key through flags or environment variables:
 
 ```bash
 export CODEJURY_API_KEY=...
-export CODEJURY_MODEL=claude-sonnet-4-6
+export CODEJURY_MODEL=claude-opus-4-8
 export CODEJURY_API_BASE=...   # optional gateway or proxy
 ```
 
+Repo Review uses a second, deliberately different model for two roles at once. On the recall
+side it finds alongside the main model, so the union takes whatever either catches and a
+single model's blind spot no longer caps recall. On the precision side it must agree before a
+candidate is refuted, so a deletion needs two models with uncorrelated blind spots and no lone
+skeptic drops a real finding. Point it at a cross-vendor model. With none set, both models
+collapse to one, the finder is single-model and the verify stage keeps every candidate, the
+recall-safe default.
+
+```bash
+export CODEJURY_CHECKER_PROVIDER=openai   # default
+export CODEJURY_CHECKER_MODEL=...         # a different model from CODEJURY_MODEL
+export CODEJURY_CHECKER_API_KEY=...
+export CODEJURY_CHECKER_API_BASE=...      # optional
+```
+
 The tool does not auto-load `.env`.
 
 Useful flags:
@@ -85,19 +107,19 @@ 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
 ```
 
@@ -119,12 +141,16 @@ codejury review repo /path/to/repo
 The workspace contains:
 
 ```text
-inventory/      attack surface, authorization model, candidates, severity rubric
+inventory/      attack surface, authorization model, seeded entrypoints, severity rubric
 units/          one review unit per candidate entrypoint
-issues/         issue write-ups
+candidates/     agent proposals, one write-up per candidate finding
+findings/       confirmed findings, written by finalize
 pocs/           runnable PoCs, when available
+findings.json   ranked machine-readable findings
 METHODOLOGY.md  full review process
 _stack.md       detected stack notes
+_refuted.md     refuted candidates and why
+_pocs.md        PoC reconciliation, planned versus delivered
 ```
 
 Then run the interactive slash command in Claude Code or Codex:
@@ -144,9 +170,10 @@ codejury review repo /path/to/repo --finalize
 codejury review repo /path/to/repo --gate
 ```
 
-`--finalize` deduplicates issue files, verifies survivors, records refuted candidates in
-`_refuted.md`, and writes ranked `findings.json`. `--gate` fails until the workspace has
-an enumerated surface, reviewed units, and calibrated findings.
+`--finalize` deduplicates candidate files, verifies survivors, writes the confirmed
+`findings/`, records refuted candidates in `_refuted.md` and PoC reconciliation in
+`_pocs.md`, and writes ranked `findings.json`. `--gate` fails until the workspace has an
+enumerated surface, reviewed units, and calibrated candidates.
 
 For a headless run, use:
 
@@ -154,18 +181,40 @@ 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:
+
+- `--reviewer model` is the default. It makes one grounded model call per unit. 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.
+- `--reviewer claude-cli` 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.
+
+Add `--checker-model`, a different model from `--model`, to enable cross-model
+verification. It finds alongside the main model on the recall side and must agree before a
+finding is dropped on the precision side. With none set, 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.
 
@@ -184,7 +233,7 @@ The tool is intentionally scoped to real exploitable application security issues
 not report dependency CVEs, style notes, generic best practices, speculation, or risks that
 only matter if production configuration leaks.
 
-## Model And Mode Guidance
+## Model and Mode Guidance
 
 Detection quality is dominated by model quality first, then mode.
 
@@ -204,18 +253,18 @@ cp examples/codejury-pr-review.yml .github/workflows/codejury-pr-review.yml
 Add `CODEJURY_API_KEY` as a repository secret. The workflow reviews the pull request diff,
 uploads SARIF to code scanning, and fails on HIGH or CRITICAL findings.
 
-## Extend The Knowledge
+## Extend the Knowledge
 
 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