Skip to content

Commit 290fe93

Browse files
Harbor404rng1995
andauthored
feat(report): expose the file surface a finding landed on (#703)
* feat(report): expose the file surface each finding landed on Add an advisory `surface` label to every reported finding: `code`, `instructions` (`SKILL.md`), `docs`, `tests`, `comments`, or `config`. It is derived from the finding's path, plus the matched line for the `comments` case, and it is exposed rather than filtered on: severity, confidence, the risk score, and the finding count are unchanged. Both report formats carry it -- JSON `issues[].surface` and SARIF `properties.surface` -- so a consumer can sort a report by surface, diff two scans per surface, or write a local suppression policy that takes on the risk explicitly instead of the scanner taking it on their behalf. Exact-match dedup now records a label per occurrence, so aggregating the same match across files does not mislabel the occurrences that live elsewhere. Fixes #326. Signed-off-by: Harbor404 <[email protected]> * fix(report): tighten surface classification Require provable comment-only lines and all covered finding lines, prefer executable source extensions and requirement manifests, preserve recorded occurrence surfaces, and document the advisory field. Signed-off-by: Harbor404 <[email protected]> * fix(report): reject inline-closed comment surfaces Treat PowerShell, PHP, Lua, and HTML inline comment closures as executable code when content follows, and correct the JSON occurrence documentation. The JSON report expands compacted groups into per-occurrence issues, so each issue carries its own surface rather than an occurrences[].surface key. Signed-off-by: Harbor404 <[email protected]> * fix(report): keep surface labels line-accurate Treat PowerShell block-comment closures anywhere on a # line as executable when code follows, and split source lines with CPython-compatible newline semantics. Add regressions for both review cases. Signed-off-by: Harbor404 <[email protected]> * fix(surface): keep regex findings off physical line numbers The comment refinement read content_lines (split on physical \n) for findings whose line numbers come from logical_line_starts, which also breaks on vertical tab, form feed, file/group/record separators, NEL and the Unicode line/paragraph separators. On a file carrying one of those extra separators the two coordinate systems disagree, so the refinement indexed a neighbouring line -- e.g. a curl ... | sh hit immediately before a # done line was reported with the comments surface, and the same mismatch reached the EA3 license filter and PE3 docs triage. Restore content_lines to content.splitlines() (its pre-PR behaviour) and skip the refinement whenever the source contains one of those separators, rather than picking one coordinate system for both. AST-derived findings keep working because the two systems only disagree on exactly those files. Adds a regression test beside the existing AST one. Signed-off-by: Harbor404 <[email protected]> --------- Signed-off-by: Harbor404 <[email protected]> Signed-off-by: Narendran Raghavan <[email protected]> Co-authored-by: Narendran Raghavan <[email protected]>
1 parent 4d65792 commit 290fe93

8 files changed

Lines changed: 595 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -864,7 +864,7 @@ The top-level shape is (this example shows a full LLM-backed scan; with `--no-ll
864864
"skill": { "name": "...", "source": "...", "scanned_at": "<ISO 8601>" },
865865
"risk_assessment": { "score": 0, "severity": "LOW", "recommendation": "SAFE" },
866866
"components": [ { "path": "...", "type": "...", "lines": 0, "executable": false, "size_bytes": 0 } ],
867-
"issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 } } ],
867+
"issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 }, "surface": "code" } ],
868868
"metadata": {
869869
"has_executable_scripts": false,
870870
"skillspector_version": "...",
@@ -891,6 +891,10 @@ The top-level shape is (this example shows a full LLM-backed scan; with `--no-ll
891891

892892
- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
893893
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mapped from severity: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
894+
- `issues[].surface` and `suppressed[].surface` are advisory, heuristic labels for where a finding landed:
895+
`code | instructions | docs | tests | comments | config`. JSON expands compacted groups into one `issues[]` entry
896+
per occurrence, each with its own `surface`; SARIF emits `properties.surface` on each result. The label is
897+
path/line-based and the scanned author can influence it, so do not use it as the sole suppression or security signal.
894898
- `metadata.llm_error` appears only when LLM analysis was requested but unavailable.
895899
- Archive-member components retain their virtual `path` and include `outer_path`, `nested_path`,
896900
and container provenance. Virtual paths identify in-memory members, not on-disk files; see

‎src/skillspector/models.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727
from typing import TYPE_CHECKING, Protocol
2828
from uuid import uuid4
2929

30+
from skillspector.surface import infer_surface
31+
3032
if TYPE_CHECKING:
3133
from skillspector.state import SkillspectorState
3234

@@ -182,6 +184,11 @@ class Finding:
182184
# Canonical unbound rule+match digest. Never replace it with a source-bound digest.
183185
match_fingerprint: str | None = None
184186
occurrences: list[dict[str, object]] = field(default_factory=list)
187+
# Reporting-only label for the file surface this finding landed on (see
188+
# ``skillspector.surface``). It is advisory metadata: it never changes
189+
# severity, confidence, scoring, or the finding count. ``None`` means
190+
# "derive from ``file`` at serialization time".
191+
surface: str | None = None
185192

186193
def fingerprint(self) -> str | None:
187194
"""Return a full-match fingerprint without exposing the matched payload."""
@@ -285,6 +292,9 @@ def to_dict(self) -> dict[str, object]:
285292
"evidence": dict(self.evidence),
286293
"match_fingerprint": self.fingerprint(),
287294
"occurrences": self._serialized_occurrences(),
295+
# Exposed, never filtered on: consumers decide what a surface is
296+
# worth, so the scanner does not hide a finding on their behalf.
297+
"surface": self.surface or infer_surface(self.file),
288298
}
289299
if self.transitive_depth:
290300
data["transitive_depth"] = self.transitive_depth

‎src/skillspector/nodes/analyzers/static_runner.py‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
build_declared_marker_views,
7575
)
7676
from skillspector.state import AnalyzerNodeResponse, SkillspectorState, transitive_remaining_seconds
77+
from skillspector.surface import COMMENTS, infer_surface
7778

7879
from .common import (
7980
LINE_BREAK_CHARS,
@@ -493,6 +494,13 @@ def _markdown_context_prefix(
493494
return ""
494495

495496

497+
# Separators that ``str.splitlines()`` honours but CPython's own line numbering
498+
# does not: vertical tab, form feed, file/group/record separators, NEL, and the
499+
# Unicode line/paragraph separators. They make the two coordinate systems used
500+
# below disagree -- see :func:`_refined_surface_line`.
501+
_EXOTIC_LINE_BREAKS = tuple(ch for ch in LINE_BREAK_CHARS if ch not in "\r\n")
502+
503+
496504
def _normalize_license_line(line: str) -> str:
497505
return " ".join(line.casefold().split())
498506

@@ -676,8 +684,15 @@ def _is_env_file_reference_in_docs(
676684
def analyzer_finding_to_finding(
677685
af: AnalyzerFinding,
678686
get_remediation_fn: Callable[[str], str] | None = None,
687+
*,
688+
line_text: str | None = None,
679689
) -> Finding:
680-
"""Convert an AnalyzerFinding (from any analyzer) to graph-state Finding."""
690+
"""Convert an AnalyzerFinding (from any analyzer) to graph-state Finding.
691+
692+
``line_text`` is the matched source line when the caller has it. It only
693+
refines a ``code``/``config`` path into the ``comments`` surface, so callers
694+
that cannot supply content still receive a path-derived classification.
695+
"""
681696
rem_fn = get_remediation_fn or get_remediation
682697
remediation = af.remediation or rem_fn(af.rule_id)
683698
category = (af.tags[0] if af.tags else None) or get_category(af.rule_id)
@@ -705,6 +720,7 @@ def analyzer_finding_to_finding(
705720
intent=None,
706721
evidence=dict(af.evidence),
707722
match_fingerprint=af.match_fingerprint,
723+
surface=infer_surface(af.location.file, line_text),
708724
)
709725

710726

@@ -959,7 +975,37 @@ def _convert_analyzer_finding(
959975
for triage_tag in ("contextual-triage", "likely-benign-context"):
960976
if triage_tag not in af.tags:
961977
af.tags.append(triage_tag)
962-
return analyzer_finding_to_finding(af)
978+
return analyzer_finding_to_finding(
979+
af, line_text=_refined_surface_line(af, path, content, content_lines)
980+
)
981+
982+
983+
def _refined_surface_line(
984+
af: AnalyzerFinding,
985+
path: str,
986+
content: str,
987+
content_lines: list[str],
988+
) -> str | None:
989+
"""The matched source line, or ``None`` when line numbering is ambiguous.
990+
991+
Findings from the pattern modules number lines with
992+
:func:`logical_line_starts`, which breaks on ``_EXOTIC_LINE_BREAKS`` as well
993+
as CR/LF; Python AST findings use CPython's physical ``\n`` count instead.
994+
The two agree only when the source contains none of those extra separators,
995+
so for such files the refinement is skipped rather than indexing
996+
``content_lines`` with a line number from the other system -- which would
997+
otherwise report a neighbouring line's surface.
998+
"""
999+
if any(ch in content for ch in _EXOTIC_LINE_BREAKS):
1000+
return None
1001+
start_line = af.location.start_line
1002+
end_line = af.location.end_line or start_line
1003+
start_index = max(0, start_line - 1)
1004+
end_index = min(len(content_lines), end_line)
1005+
covered_lines = content_lines[start_index:end_index]
1006+
if covered_lines and all(infer_surface(path, text) == COMMENTS for text in covered_lines):
1007+
return covered_lines[0]
1008+
return None
9631009

9641010

9651011
def _scan_path(

‎src/skillspector/nodes/deduplicate.py‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
OCCURRENCE_FINDING_TEXT_KEY,
1717
Finding,
1818
)
19+
from skillspector.surface import SURFACES, infer_surface
1920

2021
logger = get_logger(__name__)
2122

@@ -177,6 +178,23 @@ def _output_key(finding: Finding) -> tuple[object, ...]:
177178
)
178179

179180

181+
def _occurrence_surface(finding: Finding, occurrence: dict[str, object]) -> str:
182+
"""Return the surface label to record against one occurrence.
183+
184+
The finding's own label is reused when the occurrence sits in the finding's
185+
file. An occurrence pointing at another file (exact-match dedup aggregates
186+
across files) falls back to a path-only inference, because the matched line
187+
for that other file is not retained here.
188+
"""
189+
recorded_surface = occurrence.get("surface")
190+
if isinstance(recorded_surface, str) and recorded_surface in SURFACES:
191+
return recorded_surface
192+
file = str(occurrence.get("file", finding.file))
193+
if file == finding.file and finding.surface:
194+
return finding.surface
195+
return infer_surface(file)
196+
197+
180198
def deduplicate(findings: list[Finding]) -> list[Finding]:
181199
"""Aggregate classification-equivalent exact matches while preserving occurrences."""
182200
groups: dict[tuple[str, str, str, tuple[object, ...]], list[Finding]] = {}
@@ -205,7 +223,7 @@ def deduplicate(findings: list[Finding]) -> list[Finding]:
205223
_classification_metadata,
206224
), group in groups.items():
207225
representative = min(group, key=_representative_key)
208-
occurrences: dict[tuple[object, ...], tuple[object, object, object]] = {}
226+
occurrences: dict[tuple[object, ...], tuple[object, object, object, str]] = {}
209227
for finding in sorted(group, key=_representative_key):
210228
for occurrence in _occurrences(finding):
211229
location = (
@@ -228,6 +246,7 @@ def deduplicate(findings: list[Finding]) -> list[Finding]:
228246
finding.code_snippet or finding.context,
229247
),
230248
occurrence.get(OCCURRENCE_FINDING_TEXT_KEY, finding.finding),
249+
_occurrence_surface(finding, occurrence),
231250
),
232251
)
233252
ordered_occurrences = [
@@ -241,6 +260,7 @@ def deduplicate(findings: list[Finding]) -> list[Finding]:
241260
**({"source_digest": source_digest} if source_digest else {}),
242261
**({"source_url": source_url} if source_url else {}),
243262
**({"transitive_depth": transitive_depth} if transitive_depth else {}),
263+
**({"surface": surface} if surface else {}),
244264
OCCURRENCE_FINDING_ID_KEY: report_finding_id,
245265
OCCURRENCE_CODE_SNIPPET_KEY: report_code_snippet,
246266
OCCURRENCE_FINDING_TEXT_KEY: report_finding_text,
@@ -257,7 +277,7 @@ def deduplicate(findings: list[Finding]) -> list[Finding]:
257277
source_url,
258278
transitive_depth,
259279
),
260-
(report_finding_id, report_code_snippet, report_finding_text),
280+
(report_finding_id, report_code_snippet, report_finding_text, surface),
261281
) in sorted(
262282
occurrences.items(),
263283
key=lambda item: (

‎src/skillspector/nodes/report.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -318,10 +318,17 @@ def _expand_occurrences(findings: list[Finding]) -> list[Finding]:
318318
start_column, end_column = _occurrence_columns(finding, occurrence)
319319
provenance = _occurrence_provenance(finding, occurrence)
320320
depth_value = provenance.get("transitive_depth")
321+
occurrence_file = str(occurrence.get("file", finding.file))
322+
recorded_surface = occurrence.get("surface")
323+
occurrence_surface = (
324+
str(recorded_surface)
325+
if isinstance(recorded_surface, str) and recorded_surface
326+
else (finding.surface if occurrence_file == finding.file else None)
327+
)
321328
expanded.append(
322329
replace(
323330
occurrence_finding,
324-
file=str(occurrence.get("file", finding.file)),
331+
file=occurrence_file,
325332
start_line=start_line,
326333
end_line=end_line,
327334
start_column=start_column,
@@ -339,6 +346,10 @@ def _expand_occurrences(findings: list[Finding]) -> list[Finding]:
339346
),
340347
transitive_depth=depth_value if isinstance(depth_value, int) else 0,
341348
occurrences=[],
349+
# Prefer the occurrence's own recorded label. An occurrence
350+
# aggregated from another file keeps the surface that file's
351+
# finding carried; ``None`` falls back to a path-only label.
352+
surface=occurrence_surface,
342353
)
343354
)
344355
return expanded
@@ -409,6 +420,12 @@ def _build_sarif_properties(
409420
"""Project selected finding metadata into a SARIF properties dictionary."""
410421
occurrence_finding = _finding_for_occurrence(finding, occurrence or {})
411422
finding_dict = occurrence_finding.to_dict()
423+
recorded_surface = (occurrence or {}).get("surface")
424+
surface = (
425+
str(recorded_surface)
426+
if isinstance(recorded_surface, str) and recorded_surface
427+
else finding_dict["surface"]
428+
)
412429
metadata: dict[str, object] = {
413430
"findingId": occurrence_finding.finding_id,
414431
"severity": finding_dict["severity"],
@@ -425,6 +442,7 @@ def _build_sarif_properties(
425442
"intent": finding_dict["intent"],
426443
"tags": finding_dict["tags"],
427444
"evidence": finding_dict["evidence"],
445+
"surface": surface,
428446
}
429447
provenance = _occurrence_provenance(finding, occurrence)
430448
for key, sarif_key in (

0 commit comments

Comments
 (0)