COPS Patch Security Review
This offline workbench pins a local Git base and head to full commit IDs, reads a bounded patch and source blobs, and records changed entrypoints and candidate source-to-sink paths. It does not execute reviewed repository code.
Prerequisites and quick start
Run these commands from the repository root in an activated project environment with Python 3.11 or newer and Git available. The demo creates temporary local Git fixtures; it makes no network requests and does not execute reviewed diff content.
python3 -m cops info patch-security-review
python3 -m cops demo patch-security-review
python3 -m cops check patch-security-review
Design and data flow
The report separates observed facts, plausible scenarios, unknowns, and validated
findings. Rule matches are never automatically validated. Python rules inspect
calls to os.system, eval, exec, and shell-enabled subprocess functions;
they also recognize a requests.post or httpx.post call affected by a changed
line anywhere in its expression, including at module level, with the literal
Microsoft Graph v1.0 directory role assignment URL and a JSON payload containing
principalId, roleDefinitionId, and directoryScopeId. JavaScript rules inspect
route markers and dynamic execution calls. Other Graph clients and endpoints,
computed URLs or payloads, other languages, cross-function flow, sanitizers, and
many sinks remain unknown or uncovered. A clean report is not a safety verdict.
| Contract or artifact | Purpose | Key fields | Producer | Consumer | Validation | Example |
|---|---|---|---|---|---|---|
| Revision and patch input | Bind review to local Git objects and a bounded diff | Base SHA, head SHA, patch SHA-256, changed files | Local Git and reviewer | Static rules | Full commit resolution plus patch, file-count, and size bounds | Local base-to-head patch |
| Source blob | Supply changed source without executing it | Path, language, content, changed lines | Local Git | Language-specific rules | Blob size, path, and binary rejection | Changed Python module |
| Candidate | Record a bounded source-to-sink match | Candidate ID, path, line, boundary, impact, confidence | Static rules | Analyst and report | Rule syntax plus report limits | Changed requests.post to a Graph role-assignment endpoint |
| Validation assertion | Preserve an analyst's evaluation without elevating static confidence | Candidate ID, analyst, preconditions, disconfirming evidence | Analyst | Reviewer | Candidate existence and bounded impact/confidence | Preconditions recorded for one Graph candidate |
| Review report and playback summary | Provide reproducible review evidence | Pinned commits, patch digest, candidates, assertions, demo checks | Review CLI and demo | Analyst or maintainer | Report schema, mode-0600 output, and malicious/benign semantic checks | Malicious fixture yields a candidate; benign fixture does not |
The Graph URL can be the first positional argument or the url keyword. The
reported entrypoint is the enclosing function for calls in its body; calls in
defaults, decorators, or annotations use the enclosing definition context.
Each candidate has a changed-file path and line, an affected boundary, a
conditional impact, and confidence: limited. Impact describes what could
happen if the call is reached and its security preconditions hold. Confidence
means the bounded static rule matched source text; it is not a probability, an
exploitability judgment, or proof that a role grant occurred. The same impact and
confidence accompany an analyst's self-recorded validation assertion; that
assertion does not raise the static evidence's confidence. The report's pinned
commits and patch SHA-256 make the record reproducible for the reviewed revision.
An analyst can record a candidate validation with review.py validate --report
and --candidate-id, --analyst, --preconditions, and
--disconfirming-evidence. These fields are self-recorded assertions, not trusted
identity or approval attestation. Validation rejects reports whose selected
candidate lacks a bounded impact string or confidence: limited; regenerate
older reports before validating them. Reports print to stdout by default; use
--output only in an analyst-owned private directory. The command creates a new
mode-0600 file and refuses replacement.
Limits: 1 MiB patch, 100 changed files, 256 KiB per source file, 100 candidates, and 2 MiB report. Binary patches and oversized source are rejected. The workbench uses local Git only. It has no network calls or runtime dependency beyond Python 3.11+ and Git. Concurrent untrusted mutation of the local repository or output tree needs a separate deployment boundary.
Reviewer Git subprocesses discard inherited GIT_* controls, ignore system and
global Git configuration and attributes, disable hooks and file-system monitors,
and request diffs without external diff drivers or text conversion. Repository
objects and .git/config remain review inputs; the reviewer issues only bounded,
read-only Git commands. A platform-neutral pipe reader enforces the 15-second Git
deadline and existing byte budgets. The synthetic demo adds an empty template,
hook directory, and attributes file and disables commit and tag signing while it
creates fixtures.
Playback structure and result
The public playback:
- creates an isolated temporary Git repository;
- commits malicious and benign fixture changes with signing and local hooks disabled;
- reviews each pinned base-to-head patch without executing its content;
- records an analyst self-validation for the malicious candidate; and
- asserts the malicious and benign outcomes, offline boundary, patch identity, and temporary-state cleanup before printing one JSON document.
| Result field | Purpose |
|---|---|
schema | Identifies the output as cops.patch-security-review-playback/v1. |
execution_boundary.repository | Confirms that the playback used a temporary local Git repository. |
execution_boundary.network_calls, execution_boundary.diffs_executed | Confirm zero network calls and that reviewed content was not run. |
execution_boundary.live_integrations_validated | Remains false; the playback does not claim provider qualification. |
malicious.base, malicious.head, malicious.patch_sha256 | Pin the malicious review to exact local revisions and patch content. |
malicious.candidate_count, malicious.candidates | Report the static source-to-sink candidates. |
malicious.validated_finding_count, malicious.validated_findings | Preserve the analyst's bounded validation assertion. |
benign.candidate_count, benign.validated_finding_count | Prove that the benign fixture does not produce the malicious rule outcome. |
assessment, unknowns | Separate supported conclusions from remaining analysis limits. |
Run the registered public entry point:
python3 -m cops demo patch-security-review
Use the package runner directly only when debugging the playback implementation:
python3 plugins/vulnerability-management/patch-security-review/scripts/demo.py
The demo prints one JSON document. See the operator playback for the expected fields, contract definitions, rerun procedure, and cleanup.
Reviewing a separate patch
Resolve the local base and head through the review command. The following is a template for an existing local Git repository: replace all three uppercase or absolute-path placeholders with repository-specific values. Store report output only in a reviewer-owned private directory.
python3 plugins/vulnerability-management/patch-security-review/scripts/review.py \
review --repo /ABSOLUTE/PATH/TO/REPOSITORY --base BASE_COMMIT --head HEAD_COMMIT
Follow the end-to-end verification playbook to qualify this package's documented workflow and prepare evidence for a maturity review.