Skip to content

sodejm/patch-security-review

v0.1.0PolyForm-Noncommercial-1.0.0

Bounded offline security review of an immutable Git commit pair.

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 artifactPurposeKey fieldsProducerConsumerValidationExample
Revision and patch inputBind review to local Git objects and a bounded diffBase SHA, head SHA, patch SHA-256, changed filesLocal Git and reviewerStatic rulesFull commit resolution plus patch, file-count, and size boundsLocal base-to-head patch
Source blobSupply changed source without executing itPath, language, content, changed linesLocal GitLanguage-specific rulesBlob size, path, and binary rejectionChanged Python module
CandidateRecord a bounded source-to-sink matchCandidate ID, path, line, boundary, impact, confidenceStatic rulesAnalyst and reportRule syntax plus report limitsChanged requests.post to a Graph role-assignment endpoint
Validation assertionPreserve an analyst's evaluation without elevating static confidenceCandidate ID, analyst, preconditions, disconfirming evidenceAnalystReviewerCandidate existence and bounded impact/confidencePreconditions recorded for one Graph candidate
Review report and playback summaryProvide reproducible review evidencePinned commits, patch digest, candidates, assertions, demo checksReview CLI and demoAnalyst or maintainerReport schema, mode-0600 output, and malicious/benign semantic checksMalicious 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:

  1. creates an isolated temporary Git repository;
  2. commits malicious and benign fixture changes with signing and local hooks disabled;
  3. reviews each pinned base-to-head patch without executing its content;
  4. records an analyst self-validation for the malicious candidate; and
  5. asserts the malicious and benign outcomes, offline boundary, patch identity, and temporary-state cleanup before printing one JSON document.
Result fieldPurpose
schemaIdentifies the output as cops.patch-security-review-playback/v1.
execution_boundary.repositoryConfirms that the playback used a temporary local Git repository.
execution_boundary.network_calls, execution_boundary.diffs_executedConfirm zero network calls and that reviewed content was not run.
execution_boundary.live_integrations_validatedRemains false; the playback does not claim provider qualification.
malicious.base, malicious.head, malicious.patch_sha256Pin the malicious review to exact local revisions and patch content.
malicious.candidate_count, malicious.candidatesReport the static source-to-sink candidates.
malicious.validated_finding_count, malicious.validated_findingsPreserve the analyst's bounded validation assertion.
benign.candidate_count, benign.validated_finding_countProve that the benign fixture does not produce the malicious rule outcome.
assessment, unknownsSeparate 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.