cyberjury 0.1.0__tar.gz

cyberjury-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cyberjury-0.1.0/PKG-INFO

@@ -0,0 +1,454 @@
+Metadata-Version: 2.4
+Name: cyberjury
+Version: 0.1.0
+Summary: AI-assisted security review for code diffs and whole repositories.
+Author: eth4nr00t
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/eth4nr00t/cyberjury
+Project-URL: Repository, https://github.com/eth4nr00t/cyberjury
+Project-URL: Issues, https://github.com/eth4nr00t/cyberjury/issues
+Project-URL: Changelog, https://github.com/eth4nr00t/cyberjury/releases
+Keywords: appsec,sast,code review,llm,owasp,solidity,smart contracts,sarif
+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: 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
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: json-repair>=0.30
+Requires-Dist: anthropic>=0.40
+Requires-Dist: openai>=1.0
+Requires-Dist: claude-agent-sdk>=0.2
+Requires-Dist: slither-analyzer>=0.10
+Requires-Dist: web3>=6.0
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == "litellm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Dynamic: license-file
+
+# Cyberjury
+
+AI-assisted security review for code diffs and whole repositories.
+
+The tool has two review paths:
+
+- **Diff Review** audits a pull request or unified diff in one command.
+- **Repository Review** fans out across a whole repository, reviews focused units, deduplicates
+  candidates, verifies findings, and checks coverage with a gate.
+
+Diff Review is fast and reads only the change, so it catches what is visible in the diff.
+Cross-file business logic and invariants that span files need context from across the
+repository, which is Repository Review's job, so a clean Diff Review does not by itself clear the
+repository.
+
+Security knowledge is data. Vulnerability classes, language guides, framework guides, and
+protocol guides live in markdown under each review domain's `knowledge/` directory, for
+example `cyberjury/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.
+
+## When to Use This Tool
+
+Direct model review is often best for a small, one off check. This tool is useful when
+security review needs a repeatable harness around the model: scoped inputs, domain
+guidance, review state, verification, fail loud behavior, structured output, and gates.
+
+Use **Diff Review** for pull requests, release branches, and CI gates. It asks whether a
+code change introduced a reportable security issue.
+
+Use **Repository Review** for full repository audits, release reviews, high risk systems,
+authorization boundaries, business invariants, and smart contracts. It asks whether a
+repository was reviewed through a tracked worklist and which findings survived
+verification.
+
+For the detailed decision matrix, see
+[`docs/direct-model-review-vs-diff-and-repository-review.md`](docs/direct-model-review-vs-diff-and-repository-review.md).
+
+## Install
+
+```bash
+pip install cyberjury
+cyberjury install-slash-command
+```
+
+That is the whole setup. `pip install cyberjury` pulls everything a normal review needs, the
+Anthropic and OpenAI backends and the Claude Code subscription transport, with no extras to
+choose. `cyberjury install-slash-command` drops the `/cyberjury-review` command into both the
+Claude Code and Codex command directories, so it works in either agent: run it on a repository
+directory for a whole-repository review, or on a diff file or git range for a diff review.
+
+## Configure a Model Backend
+
+Set a provider key, or run keyless on your Claude Code subscription with `--executor subscription`:
+
+```bash
+export CYBERJURY_MODEL=claude-opus-4-8
+export CYBERJURY_API_KEY=...
+export CYBERJURY_API_BASE=...   # optional gateway or proxy
+export CYBERJURY_WIRE_API=chat  # set responses for a GPT-5 reasoning model, see below
+```
+
+An OpenAI GPT-5 reasoning model answers on the Responses API, not Chat Completions, so set
+`CYBERJURY_WIRE_API=responses` or pass `--wire-api responses` for the base model, otherwise the
+call comes back blank and the review fails loud. Chat is the default and fits the other models.
+
+The CLI loads a `.env` from the working directory at startup, so a project can set its provider
+config once instead of exporting it every session. A value already exported in the shell wins
+over the file, and a missing file is fine. The auto-load is a CLI convenience, so importing the
+library directly does not read `.env`.
+
+Useful flags:
+
+- `--provider anthropic|openai|litellm`
+- `--model <model>`
+- `--api-key <key>`
+- `--api-base <url>`
+- `--wire-api chat|responses`
+- `--retries <n>`
+- `--timeout <seconds>`
+
+### Cross-Model Review
+
+A single-model run needs only the setup above. For stronger verification, 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`. 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:
+`CYBERJURY_<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 override only the seat you want to change, and 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 CYBERJURY_CHALLENGER_PROVIDER=openai
+export CYBERJURY_CHALLENGER_MODEL=...             # a GPT model, the skeptic
+export CYBERJURY_CHALLENGER_API_KEY=...
+export CYBERJURY_CHALLENGER_WIRE_API=responses    # the GPT-5 reasoning models speak Responses
+export CYBERJURY_JUDGE_MODEL=...                  # a Claude model, the confirmer, distinct from the challenger
+```
+
+The same `CYBERJURY_FINDER_*` / `CYBERJURY_CHALLENGER_*` / `CYBERJURY_JUDGE_*` and the matching
+`--finder-* / --challenger-* / --judge-*` flags work on both `review diff` and `review repository`.
+Note that `review repository --run` finds with one model, the 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.
+
+## Diff Review
+
+Diff Review is the fast coded path. It audits a unified diff with either a standard
+single model call or an adversarial Finder, Challenger, and Judge pass.
+
+```text
+cyberjury review diff [--file <file> | --git-range <range>] [options]
+```
+
+```bash
+# review a diff file
+cyberjury review diff --file changes.diff
+
+# review a git range
+cyberjury review diff --repository /path/to/app --git-range origin/main...HEAD
+
+# review stdin
+git diff HEAD~1 | cyberjury review diff
+
+# use adversarial mode for extra recall on subtle cross-file logic
+cyberjury review diff --file changes.diff --mode adversarial
+
+# emit SARIF and fail on HIGH or CRITICAL findings
+cyberjury review diff --file changes.diff --format sarif --fail-on high
+
+# review with no provider key, riding your Claude Code subscription
+cyberjury review diff --file changes.diff --executor subscription
+
+# carry fetched source provenance into the report, see Fetch Verified Source
+cyberjury review diff --file changes.diff --source-meta target/cyberjury-source.json
+
+# run adversarial mode with a keyless Claude finder and judge plus an OpenAI challenger on its own key
+cyberjury 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 Repository 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 repository agent, the diff agent
+answers from the diff in the prompt and reads no files.
+
+`cyberjury review diff --dry-run` uses a mock provider and a built-in demo diff, so it needs
+no API key.
+
+## Repository Review
+
+Repository Review is the recall-first path for whole repositories. A whole codebase is too large
+for one useful model call, so the tool creates a workspace, builds a unit worklist, and
+reviews focused units instead of doing one shallow pass.
+
+```text
+cyberjury review repository <repository> (--scaffold | --run | --finalize | --gate) [--invariants <file>] [options]
+```
+
+### From an Agent
+
+In Claude Code or Codex, one command runs the whole review, scaffold, fan-out, finalize, and gate:
+
+```text
+/cyberjury-review <target> [--coded] [--domain auto|web|evm] [--effort low|medium|high] [--invariants <file>] [--workspace <path>]
+```
+
+`--coded` picks the engine and the model backend together. Without it, the default, a
+repository is reviewed by the agent fan-out on your Claude Code subscription, so your `.env`
+provider config is not used. With it, Cyberjury's own coded engine reviews the repository through `--run` on
+`--executor api`, so your `.env` provider config is used throughout. The slash command
+announces the choice on its first line, so which backend ran is never a guess. In the default
+fan-out mode the agent maps the attack surface, fills the authorization model, runs one focused
+sub-review per unit, records findings, and leaves deterministic post-processing to code. PoCs
+run only against sandbox or dev environments, never production.
+
+### From the CLI
+
+The slash command runs these four steps for you. Only the second, the find step, changes: `--run`
+drives the coded engine below, or an agent fans out over the units, the default when the slash
+command runs it. Scaffold, finalize, and gate are the same either way. Run them yourself for a
+headless or CI review, or to drive the coded engine without an agent:
+
+```bash
+cyberjury review repository /path/to/repository --scaffold     # build the workspace and unit worklist
+cyberjury review repository /path/to/repository --run          # coded multi-pass review to convergence
+cyberjury review repository /path/to/repository --finalize     # dedup candidates, verify, write findings
+cyberjury review repository /path/to/repository --gate         # check coverage, non-zero until it is met
+```
+
+`--run` reviews every unit each pass, cycles lenses until convergence, verifies inline, and writes
+the confirmed `findings/`, so on the coded path `--finalize` is optional. See Review Strategy for
+how each unit is reviewed. `--finalize` deduplicates and verifies the candidates an agent fan-out
+proposed, the step the agent path needs, records refuted candidates in `_refuted.md` and PoC
+reconciliation in `_pocs.md`, and writes the confirmed `findings/` and the ranked `findings.json`. `--gate` fails until the workspace has an enumerated
+surface, reviewed units, and calibrated candidates. Add `--strict-coverage` to also fail when a
+source file is owned by no unit, instead of noting it. Add `--poc` on finalize to write a runnable
+PoC for each confirmed finding when the domain binds a PoC backend. Where the domain runs safely and
+locally it also runs the PoC, such as the EVM Foundry reproducer, which compiles and runs the test
+with no fork, no broadcast, and no key. A web PoC is written for a human to run against a sandbox or
+dev host, never automatically, since it needs a live server and credentials. It is off by default
+since it calls a model per finding, and for EVM also compiles and runs one. When the run toolchain
+is absent the PoC is written but not run, with a note on how to run it by hand, rather than failing.
+It only adds evidence, so a finding is kept whether or not its PoC reproduces.
+
+### The Workspace
+
+Scaffold creates a private workspace holding:
+
+```text
+inventory/      attack surface, authorization model, seeded entrypoints, severity rubric
+units/          one review unit per candidate entrypoint
+candidates/     agent proposals, one write-up per candidate finding
+findings/       confirmed findings, written by --run or 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
+```
+
+To seed intent invariants, the business rules only you know that a static read cannot infer, keep
+an invariants file with the repository and pass `--invariants <path>` to scaffold. It imports the
+file into `inventory/_invariants.md` and never overwrites an edited one, so clear the workspace
+with `--fresh` to replace it. Write one rule per line as `only <who> may <operation> <asset>,
+under <condition>`. Leave it out to seed nothing.
+
+### 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. Facts 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, which is what gives a smart contract review its call
+  relationships and co-locates a cross-function path the file slices would otherwise split.
+  A domain with a backend, the EVM domain, grounds with facts by default, except at `--effort
+  low`, the cheap fast tier where the pass stays file-slice only. When the toolchain is absent
+  or the target does not compile the review degrades to file-slice review with a loud note
+  rather than failing. Pass `--no-facts` to force it off for a faster pass, or `--facts` to
+  force it on where it is not the default.
+- `--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.
+
+The subscription backend keeps a Claude Agent SDK session alive across calls by default,
+amortizing the Claude Code startup that a fresh `claude -p` per call would pay on a many-call
+Repository Review run. The SDK ships in the base install. Set `CYBERJURY_CLAUDE_TRANSPORT=process`
+for one `claude -p` per call. An unknown transport value fails at startup rather than silently
+falling back.
+
+`--effort low|medium|high` is the one depth dial, each level fixing three things at once:
+
+| `--effort` | Shots per lens | Skeptics to drop a candidate | Facts default |
+|:---|:---|:---|:---|
+| `low` | 1 | 1 | Off |
+| `medium` (default) | 2 | 1 | On |
+| `high` | 3 | 2 | On |
+
+`--min-lens-shots` and `--votes` override the shot and skeptic columns, and `--facts` or
+`--no-facts` overrides the facts column.
+
+On the subscription backend the concurrency within a pass defaults to 2 so a wide fan-out does not
+trip the shared rate cap, and to 6 on an API key, override it with `--concurrency`.
+
+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.
+
+## 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 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.
+- Repository Review with `--executor api` sends bounded source snippets, the detected stack
+  notes, the vulnerability guidance, and the findings.
+- 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 repository 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 `CYBERJURY_API_KEY` environment variable over
+`--api-key`, since a flag can leak through shell history and process listings. The review
+workspace and the generated reports hold exploit paths, sensitive file locations, and
+PoCs, so treat them as sensitive. The workspace is created private, mode `0700`.
+
+## Fetch Verified Source
+
+Review a deployed contract by first pulling its verified source from a block explorer, then
+running Repository Review on the local tree:
+
+```text
+cyberjury fetch source --address <address> --out <dir> [options]
+```
+
+```bash
+cyberjury fetch source --chain eth --address 0x... --out ./target
+cyberjury review repository ./target --domain evm --run
+```
+
+`fetch source` queries the Etherscan V2 API, which serves every supported chain from one
+endpoint with one key, so a single `CYBERJURY_ETHERSCAN_API_KEY` covers `arbitrum`, `bsc`,
+`eth`, and `polygon`, chosen with `--chain`. Pass the key with `--api-key` or that
+environment variable.
+It writes the reconstructed source tree and a `cyberjury-source.json` recording the chain,
+address, compiler, and source URL, and it fails loud on an unverified or malformed response.
+It never runs a review on its own. Point Diff Review at that metadata file with
+`--source-meta` to carry the provenance into the report.
+
+## Supported Knowledge
+
+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, OIDC, GraphQL, and MCP
+
+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.
+
+## Findings
+
+Every reportable finding should have:
+
+- file and line
+- severity
+- category
+- description
+- exploit scenario
+- recommendation
+- confidence or verification status
+
+The tool is intentionally scoped to real exploitable application security issues. It should
+not report dependency CVEs, style notes, generic best practices, speculation, or risks that
+only matter if production configuration leaks.
+
+## Model and Mode Guidance
+
+Detection quality is dominated by model quality first, then mode.
+
+- Use standard mode with a strong model by default.
+- Use adversarial mode when you want extra recall on subtle cross-file logic.
+- Do not use adversarial mode as a false-positive reducer. False positives are controlled
+  by the do-not-report guidance, deterministic filtering, and verification.
+
+## GitHub Actions
+
+Use the example workflow:
+
+```bash
+cp examples/cyberjury-pr-review.yml .github/workflows/cyberjury-pr-review.yml
+```
+
+Add `CYBERJURY_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
+
+Add security knowledge as markdown:
+
+- Vulnerability class:
+  `cyberjury/domains/<domain>/knowledge/vulnerabilities/<id>.md`
+- Language guide:
+  `cyberjury/domains/<domain>/knowledge/guides/languages/<language>.md`
+- Framework guide:
+  `cyberjury/domains/<domain>/knowledge/guides/frameworks/<language>/<framework>.md`
+- Protocol guide:
+  `cyberjury/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
+capability.
+
+## Development
+
+Run tests in a virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```