Skip to content

Commit 0e69eac

Browse files
authored
Merge pull request #22 from CoreTrace/feat/reporters
feat: findings reporters and --check
2 parents 2f973d0 + 1f782c6 commit 0e69eac

11 files changed

Lines changed: 618 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,17 @@ python -m pytest
2424
python -m ruff check .
2525
```
2626

27+
## Check a file with plugins
28+
29+
```bash
30+
coretrace-python-analyzer --check app.py --plugins plugins/
31+
coretrace-python-analyzer --check app.py --plugins plugins/ --format sarif > report.sarif
32+
```
33+
34+
`--plugins` is a directory searched recursively for `plugin.toml` manifests and may be
35+
repeated. `--format` is `text` (default), `json` or `sarif`. Exit status is 0 when nothing
36+
was found, 1 when findings were reported, and 2 on a usage or analysis error.
37+
2738
## Emit PyIR
2839

2940
```bash

‎src/coretrace_python/cli.py‎

Lines changed: 58 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,40 @@
44
import sys
55
from pathlib import Path
66

7+
from coretrace_python import engine
8+
from coretrace_python.analysis import AnalysisError
9+
from coretrace_python.cfg import CFGError
710
from coretrace_python.frontend import HIRBuildError, ParseError, build_hir
811
from coretrace_python.ir.lowering import LoweringError, lower_module
912
from coretrace_python.ir.printer import format_module
13+
from coretrace_python.plugins import IncompatiblePluginError, ManifestError
14+
from coretrace_python.reporters import FORMATS, render
1015
from coretrace_python.semantic.imports import ImportResolutionError
1116
from coretrace_python.semantic.scopes import ScopeError
1217
from coretrace_python.source import SourceManager
1318

19+
EXIT_CLEAN = 0
20+
EXIT_FINDINGS = 1
21+
EXIT_ERROR = 2
22+
23+
_ANALYSIS_ERRORS = (
24+
OSError,
25+
UnicodeError,
26+
ParseError,
27+
HIRBuildError,
28+
ImportResolutionError,
29+
ScopeError,
30+
CFGError,
31+
LoweringError,
32+
AnalysisError,
33+
ManifestError,
34+
IncompatiblePluginError,
35+
)
36+
1437

1538
def build_parser() -> argparse.ArgumentParser:
1639
parser = argparse.ArgumentParser(
17-
prog="coretrace-python-analyzer",
40+
prog=engine.TOOL_NAME,
1841
description="Analyze Python source with CoreTrace.",
1942
)
2043
parser.add_argument("path", type=Path, help="Python source file to analyze")
@@ -28,32 +51,49 @@ def build_parser() -> argparse.ArgumentParser:
2851
action="store_true",
2952
help="with --emit-ir, print the static single assignment form",
3053
)
54+
parser.add_argument(
55+
"--check",
56+
action="store_true",
57+
help="run the loaded plugins and report their findings",
58+
)
59+
parser.add_argument(
60+
"--plugins",
61+
action="append",
62+
type=Path,
63+
default=[],
64+
metavar="DIR",
65+
help="with --check, a directory searched recursively for plugin.toml (repeatable)",
66+
)
67+
parser.add_argument(
68+
"--format",
69+
choices=sorted(FORMATS),
70+
default=None,
71+
help="with --check, the report format (default: text)",
72+
)
3173
return parser
3274

3375

3476
def main(argv: list[str] | None = None) -> int:
3577
args = build_parser().parse_args(argv)
36-
if not args.emit_ir:
37-
print("error: no action selected; pass --emit-ir", file=sys.stderr)
38-
return 2
78+
if not (args.emit_ir or args.check):
79+
print("error: no action selected; pass --emit-ir or --check", file=sys.stderr)
80+
return EXIT_ERROR
81+
if args.format is not None and not args.check:
82+
print("error: --format only applies to --check", file=sys.stderr)
83+
return EXIT_ERROR
3984

4085
try:
4186
source = SourceManager().load_file(args.path)
42-
module = lower_module(build_hir(source), ssa=args.ssa)
43-
except (
44-
OSError,
45-
UnicodeError,
46-
ParseError,
47-
HIRBuildError,
48-
ImportResolutionError,
49-
ScopeError,
50-
LoweringError,
51-
) as error:
87+
if args.emit_ir:
88+
print(format_module(lower_module(build_hir(source), ssa=args.ssa)))
89+
if args.check:
90+
findings = engine.check(source, args.plugins)
91+
print(render(args.format or "text", engine.report(findings)), end="")
92+
return EXIT_FINDINGS if findings else EXIT_CLEAN
93+
except _ANALYSIS_ERRORS as error:
5294
print(f"error: {error}", file=sys.stderr)
53-
return 1
54-
55-
print(format_module(module))
56-
return 0
95+
return EXIT_ERROR
96+
return EXIT_CLEAN
5797

5898

5999
if __name__ == "__main__":

‎src/coretrace_python/engine.py‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
"""Composition root: the full analysis DAG, plugin loading and one check run.
2+
3+
This is the only module that knows every layer. The CLI and future hosts call it;
4+
plugins and analyses never import it.
5+
"""
6+
7+
from __future__ import annotations
8+
9+
from collections.abc import Sequence
10+
from pathlib import Path
11+
12+
from coretrace_python import __version__
13+
from coretrace_python.abstract import ConstantPropagation
14+
from coretrace_python.analysis import AnalysisManager, AnyAnalysis
15+
from coretrace_python.cfg import CFGAnalysis, DominanceAnalysis, PostDominanceAnalysis
16+
from coretrace_python.findings import Finding
17+
from coretrace_python.frontend import build_hir
18+
from coretrace_python.hir import nodes
19+
from coretrace_python.ir.defuse import DefUseAnalysis
20+
from coretrace_python.ir.lowering import ModuleIRAnalysis, PyIRAnalysis
21+
from coretrace_python.ir.ssa import SSAAnalysis
22+
from coretrace_python.plugins import PluginRegistry, discover_plugins, run_plugins
23+
from coretrace_python.reporters import Report
24+
from coretrace_python.semantic import SEMANTIC_ANALYSES
25+
from coretrace_python.source import SourceFile
26+
from coretrace_python.taint import SecurityModelAnalysis, SecurityModelRegistry, TaintAnalysis
27+
28+
TOOL_NAME = "coretrace-python-analyzer"
29+
30+
ALL_ANALYSES: tuple[AnyAnalysis, ...] = (
31+
*SEMANTIC_ANALYSES,
32+
CFGAnalysis,
33+
DominanceAnalysis,
34+
PostDominanceAnalysis,
35+
PyIRAnalysis,
36+
ModuleIRAnalysis,
37+
SSAAnalysis,
38+
DefUseAnalysis,
39+
ConstantPropagation,
40+
SecurityModelAnalysis,
41+
TaintAnalysis,
42+
)
43+
44+
45+
def build_manager(module: nodes.Module, models: SecurityModelRegistry | None = None) -> AnalysisManager:
46+
"""A manager with every engine analysis registered and the security models provided."""
47+
48+
manager = AnalysisManager(module)
49+
manager.register(*ALL_ANALYSES)
50+
manager.provide(SecurityModelAnalysis, (models or SecurityModelRegistry()).freeze())
51+
return manager
52+
53+
54+
def check(source: SourceFile, plugin_roots: Sequence[Path]) -> tuple[Finding, ...]:
55+
"""Run every plugin found under ``plugin_roots`` against ``source``."""
56+
57+
manager = build_manager(build_hir(source))
58+
registry = PluginRegistry()
59+
for root in plugin_roots:
60+
for loaded in discover_plugins(root, manager):
61+
registry.add(loaded)
62+
return run_plugins(manager, [loaded.plugin for loaded in registry])
63+
64+
65+
def report(findings: Sequence[Finding]) -> Report:
66+
return Report(tuple(findings), TOOL_NAME, __version__)
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""Reporters render normalized findings and never run an analysis (architecture §28)."""
2+
3+
from __future__ import annotations
4+
5+
from collections.abc import Callable, Mapping
6+
from types import MappingProxyType
7+
8+
from coretrace_python.reporters.json_format import render_json
9+
from coretrace_python.reporters.report import Report
10+
from coretrace_python.reporters.sarif import render_sarif
11+
from coretrace_python.reporters.text import render_text
12+
13+
FORMATS: Mapping[str, Callable[[Report], str]] = MappingProxyType(
14+
{"text": render_text, "json": render_json, "sarif": render_sarif}
15+
)
16+
17+
18+
def render(format_name: str, report: Report) -> str:
19+
return FORMATS[format_name](report)
20+
21+
22+
__all__ = ["FORMATS", "Report", "render", "render_json", "render_sarif", "render_text"]
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
"""JSON reporter: versioned normalized finding records."""
2+
3+
from __future__ import annotations
4+
5+
import json
6+
7+
from coretrace_python.findings import FINDING_SCHEMA_VERSION, Finding
8+
from coretrace_python.reporters.report import Report
9+
10+
11+
def finding_record(finding: Finding) -> dict[str, object]:
12+
span = finding.span
13+
return {
14+
"rule_id": finding.rule_id,
15+
"message": finding.message,
16+
"severity": finding.severity.value,
17+
"confidence": finding.confidence.value,
18+
"location": {
19+
"path": str(span.source_id),
20+
"line": span.start_line,
21+
"column": span.start_column,
22+
"end_line": span.end_line,
23+
"end_column": span.end_column,
24+
},
25+
"function": finding.function,
26+
"metadata": dict(finding.metadata),
27+
}
28+
29+
30+
def render_json(report: Report) -> str:
31+
document = {
32+
"schema_version": FINDING_SCHEMA_VERSION,
33+
"tool": {"name": report.tool_name, "version": report.tool_version},
34+
"findings": [finding_record(finding) for finding in report.findings],
35+
}
36+
return json.dumps(document, indent=2) + "\n"
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""The normalized report every reporter renders (architecture §23, §28)."""
2+
3+
from __future__ import annotations
4+
5+
from dataclasses import dataclass
6+
7+
from coretrace_python.findings import Finding
8+
9+
10+
def _order(finding: Finding) -> tuple[str, int, int, str]:
11+
span = finding.span
12+
return (str(span.source_id), span.start_line, span.start_column, finding.rule_id)
13+
14+
15+
@dataclass(frozen=True)
16+
class Report:
17+
findings: tuple[Finding, ...]
18+
tool_name: str
19+
tool_version: str
20+
21+
def __post_init__(self) -> None:
22+
object.__setattr__(self, "findings", tuple(sorted(self.findings, key=_order)))
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
"""SARIF 2.1.0 reporter."""
2+
3+
from __future__ import annotations
4+
5+
import json
6+
7+
from coretrace_python.findings import Finding, Severity
8+
from coretrace_python.reporters.report import Report
9+
10+
SARIF_VERSION = "2.1.0"
11+
SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
12+
13+
_LEVELS = {
14+
Severity.CRITICAL: "error",
15+
Severity.HIGH: "error",
16+
Severity.MEDIUM: "warning",
17+
Severity.LOW: "note",
18+
Severity.INFO: "note",
19+
}
20+
21+
22+
def _result(finding: Finding, rule_index: int) -> dict[str, object]:
23+
span = finding.span
24+
region: dict[str, int] = {"startLine": span.start_line, "startColumn": span.start_column}
25+
if span.end_line is not None and span.end_column is not None:
26+
region["endLine"] = span.end_line
27+
region["endColumn"] = span.end_column
28+
return {
29+
"ruleId": finding.rule_id,
30+
"ruleIndex": rule_index,
31+
"level": _LEVELS[finding.severity],
32+
"message": {"text": finding.message},
33+
"locations": [
34+
{
35+
"physicalLocation": {
36+
"artifactLocation": {"uri": str(span.source_id)},
37+
"region": region,
38+
}
39+
}
40+
],
41+
}
42+
43+
44+
def render_sarif(report: Report) -> str:
45+
rule_ids: list[str] = []
46+
for finding in report.findings:
47+
if finding.rule_id not in rule_ids:
48+
rule_ids.append(finding.rule_id)
49+
document = {
50+
"$schema": SARIF_SCHEMA,
51+
"version": SARIF_VERSION,
52+
"runs": [
53+
{
54+
"tool": {
55+
"driver": {
56+
"name": report.tool_name,
57+
"version": report.tool_version,
58+
"rules": [
59+
{"id": rule_id, "shortDescription": {"text": rule_id}}
60+
for rule_id in rule_ids
61+
],
62+
}
63+
},
64+
"results": [
65+
_result(finding, rule_ids.index(finding.rule_id)) for finding in report.findings
66+
],
67+
}
68+
],
69+
}
70+
return json.dumps(document, indent=2) + "\n"
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""Plain-text reporter: one ``path:line:column`` line per finding and a summary."""
2+
3+
from __future__ import annotations
4+
5+
from coretrace_python.reporters.report import Report
6+
7+
8+
def render_text(report: Report) -> str:
9+
lines = []
10+
for finding in report.findings:
11+
span = finding.span
12+
line = (
13+
f"{span.source_id}:{span.start_line}:{span.start_column}: "
14+
f"{finding.severity.value} {finding.rule_id}: {finding.message}"
15+
)
16+
if finding.function is not None:
17+
line += f" [{finding.function}]"
18+
lines.append(line)
19+
count = len(report.findings)
20+
summary = "no findings" if count == 0 else f"{count} finding{'s' if count > 1 else ''}"
21+
lines.append(summary)
22+
return "\n".join(lines) + "\n"

‎tests/test_architecture.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
}
4242

4343
# Top-level modules that wire the pipeline together and may import any layer.
44-
ROOT_MODULES = {"__init__", "__main__", "cli"}
44+
ROOT_MODULES = {"__init__", "__main__", "cli", "engine"}
4545

4646

4747
def package_files() -> Iterator[tuple[Path, str, str]]:

0 commit comments

Comments
 (0)