Coverage for src/governed_harness/validators/review.py: 100%
61 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import re
4from collections.abc import Iterator
5from dataclasses import dataclass
6from datetime import UTC, datetime
8from governed_harness.domain.enums import ActorType, FindingSeverity, ResultStatus, ValidationKind
9from governed_harness.domain.ids import new_id
10from governed_harness.domain.models import Actor, Finding, FindingLocation, ValidationResult
11from governed_harness.validators.base import ValidationContext, ValidatorOutput
14@dataclass(frozen=True)
15class ReviewRule:
16 rule_id: str
17 category: str
18 severity: FindingSeverity
19 pattern: re.Pattern[str]
20 message: str
21 recommendation: str
24RULES = (
25 ReviewRule(
26 "review.possible-secret",
27 "security",
28 FindingSeverity.CRITICAL,
29 re.compile(
30 r"(?i)(github_pat_|gh[pousr]_|AKIA[A-Z0-9]{16}|password\s*[:=]\s*['\"][^'\"]{4,})"
31 ),
32 "The added content appears to contain a credential or secret.",
33 "Remove the secret, rotate it when applicable, and use an approved secret handle.",
34 ),
35 ReviewRule(
36 "review.shell-true",
37 "security",
38 FindingSeverity.HIGH,
39 re.compile(r"\bshell\s*=\s*True\b"),
40 "A subprocess is executed through a shell.",
41 "Use an argv vector with shell disabled and validate every argument.",
42 ),
43 ReviewRule(
44 "review.dynamic-eval",
45 "security",
46 FindingSeverity.HIGH,
47 re.compile(r"\b(?:eval|exec)\s*\("),
48 "Dynamic code execution was added.",
49 "Replace dynamic execution with a constrained parser or explicit dispatch table.",
50 ),
51 ReviewRule(
52 "review.todo",
53 "maintainability",
54 FindingSeverity.MEDIUM,
55 re.compile(r"\b(?:TODO|FIXME)\b"),
56 "A TODO or FIXME was introduced in changed code.",
57 "Resolve it now or link it to a tracked, owned follow-up with rationale.",
58 ),
59)
62class IndependentReviewValidator:
63 validator_id = "review.independent"
65 def __init__(self, skip_rules: frozenset[str] = frozenset()) -> None:
66 # verification.secrets: context replaces the style-dependent secret pattern with the
67 # context-aware check of VERIFICATION, so the review does not report it twice.
68 self.skip_rules = skip_rules
70 def execute(self, context: ValidationContext) -> ValidatorOutput:
71 actor = Actor(
72 actor_type=ActorType.TOOL, actor_id="validator.independent-review", version="1"
73 )
74 started = datetime.now(UTC)
75 if context.raw_diff is not None:
76 diff = context.raw_diff
77 else:
78 # Backward-compatible fallback for callers that do not provide an
79 # ephemeral raw diff. Persisted evidence may be redacted, so the
80 # orchestration engine should always supply raw_diff for security review.
81 diff_bytes = context.artifact_store.get(context.change_set.diff_ref)
82 diff = diff_bytes.decode("utf-8", "replace")
83 findings = list(self._scan(diff, context, actor))
84 source_changed = any(
85 change.path.startswith(("src/", "lib/", "app/")) for change in context.change_set.files
86 )
87 tests_changed = any(
88 change.path.startswith(("test/", "tests/"))
89 or "/test/" in change.path
90 or "/tests/" in change.path
91 for change in context.change_set.files
92 )
93 if source_changed and not tests_changed:
94 findings.append(
95 Finding(
96 finding_id=new_id("finding"),
97 execution_id=context.execution_id,
98 validator_id=self.validator_id,
99 rule_id="review.source-without-test-change",
100 category="tests",
101 severity=FindingSeverity.MEDIUM,
102 message="Production source changed without a corresponding test-file change.",
103 recommendation="Confirm existing tests cover the behavior or add a targeted regression test.",
104 evidence_refs=(context.change_set.diff_ref,),
105 introduced=True,
106 provenance=context.provenance.model_copy(update={"actor": actor}),
107 )
108 )
109 report = context.artifact_store.put_json(
110 {
111 "validatorId": self.validator_id,
112 "changeSetDigest": context.change_set.digest,
113 "findingIds": [finding.finding_id for finding in findings],
114 "rulesEvaluated": [
115 rule.rule_id for rule in RULES if rule.rule_id not in self.skip_rules
116 ]
117 + ["review.source-without-test-change"],
118 },
119 metadata={"kind": "independent-review"},
120 )
121 result = ValidationResult(
122 validation_result_id=new_id("validation"),
123 execution_id=context.execution_id,
124 validator_id=self.validator_id,
125 change_set_digest=context.change_set.digest,
126 status=ResultStatus.PASSED,
127 kind=ValidationKind.SUCCESS,
128 mandatory=True,
129 summary=f"Independent review completed with {len(findings)} finding(s)",
130 finding_ids=tuple(finding.finding_id for finding in findings),
131 evidence_refs=(context.change_set.diff_ref, report.uri),
132 started_at=started,
133 finished_at=datetime.now(UTC),
134 provenance=context.provenance.model_copy(update={"actor": actor}),
135 )
136 return ValidatorOutput(result, tuple(findings))
138 def _scan(self, diff: str, context: ValidationContext, actor: Actor) -> Iterator[Finding]:
139 current_path: str | None = None
140 current_line = 0
141 for raw_line in diff.splitlines():
142 if raw_line.startswith("+++ b/"):
143 current_path = raw_line[6:]
144 continue
145 if raw_line.startswith("@@"):
146 current_line = _hunk_start(raw_line)
147 continue
148 if raw_line.startswith("+") and not raw_line.startswith("+++"):
149 yield from self._line_findings(
150 raw_line[1:], current_path, current_line, context, actor
151 )
152 current_line += 1
153 elif raw_line.startswith(" "):
154 current_line += 1
156 def _line_findings(
157 self,
158 content: str,
159 path: str | None,
160 line: int,
161 context: ValidationContext,
162 actor: Actor,
163 ) -> Iterator[Finding]:
164 """The findings of the rules that match one added line."""
165 for rule in RULES:
166 if rule.rule_id in self.skip_rules:
167 continue
168 if rule.pattern.search(content):
169 yield Finding(
170 finding_id=new_id("finding"),
171 execution_id=context.execution_id,
172 validator_id=self.validator_id,
173 rule_id=rule.rule_id,
174 category=rule.category,
175 severity=rule.severity,
176 message=rule.message,
177 location=FindingLocation(
178 path=path,
179 start_line=line or None,
180 end_line=line or None,
181 ),
182 evidence_refs=(context.change_set.diff_ref,),
183 recommendation=rule.recommendation,
184 introduced=True,
185 provenance=context.provenance.model_copy(update={"actor": actor}),
186 )
189def _hunk_start(header: str) -> int:
190 """The first new-file line of a ``@@`` hunk header; 0 without one."""
191 match = re.search(r"\+(\d+)", header)
192 return int(match.group(1)) if match else 0