securelint 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
securelint/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """SecureLint: a security scanner and CI policy gate for Python projects."""
2
+
3
+ __version__ = "1.0.0"
securelint/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Entry point for ``python -m securelint``."""
2
+
3
+ from securelint.cli import main
4
+
5
+ raise SystemExit(main())
securelint/baseline.py ADDED
@@ -0,0 +1,139 @@
1
+ """Tell the problems a project already knows about from new ones.
2
+
3
+ A project that starts using SecureLint may have many findings it cannot
4
+ fix at once. If every scan failed because of them, the tool would simply
5
+ be turned off. The baseline lets the project accept what exists today
6
+ and still stop anything new::
7
+
8
+ securelint baseline # remember today's findings in a file
9
+ securelint scan # from now on, only new findings count
10
+
11
+ The baseline is a small JSON file kept at the top of the project and
12
+ committed with the code, so the whole team shares it and every change to
13
+ it is visible in code review. It holds the fingerprint of each known
14
+ finding (see ``securelint.fingerprint``), which is why a known finding
15
+ stays known when the lines around it move.
16
+ """
17
+
18
+ import json
19
+ from collections.abc import Sequence
20
+ from dataclasses import replace
21
+ from pathlib import Path
22
+ from typing import Any
23
+
24
+ from securelint.engine import ScanResult
25
+ from securelint.model import Finding
26
+
27
+ BASELINE_FILE_NAME = ".securelint-baseline.json"
28
+
29
+ BASELINE_FORMAT_VERSION = 1
30
+ """Raised if the file's layout changes in a way older versions cannot read."""
31
+
32
+
33
+ class BaselineError(Exception):
34
+ """The baseline file cannot be used; the message says why."""
35
+
36
+
37
+ def find_project_root(target: Path) -> Path:
38
+ """Return the top directory of the project that ``target`` belongs to.
39
+
40
+ That is the nearest directory, starting at ``target`` and going up,
41
+ that holds a baseline file or is the top of a Git repository. Without
42
+ either, it is the scanned directory itself.
43
+ """
44
+ start = target.resolve()
45
+ if not start.is_dir():
46
+ start = start.parent
47
+ for directory in (start, *start.parents):
48
+ if (directory / BASELINE_FILE_NAME).is_file():
49
+ return directory
50
+ if (directory / ".git").exists():
51
+ return directory
52
+ return start
53
+
54
+
55
+ def save_baseline(path: Path, findings: Sequence[Finding]) -> None:
56
+ """Write the baseline file listing ``findings`` as known."""
57
+ entries = sorted(
58
+ (
59
+ {
60
+ "fingerprint": finding.fingerprint,
61
+ # The rule and the file are for the person reading the
62
+ # file or its diff; only the fingerprint is used to match.
63
+ # The line number is left out on purpose: it would be
64
+ # wrong as soon as the code above it changed.
65
+ "rule_id": finding.rule_id,
66
+ "path": finding.path,
67
+ }
68
+ for finding in findings
69
+ ),
70
+ key=lambda entry: (entry["path"], entry["rule_id"], entry["fingerprint"]),
71
+ )
72
+ document = {
73
+ "format_version": BASELINE_FORMAT_VERSION,
74
+ "tool": "securelint",
75
+ "findings": entries,
76
+ }
77
+ # One entry per line and a fixed order, so adding or removing a finding
78
+ # changes only its own lines in a diff.
79
+ path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
80
+
81
+
82
+ def load_baseline(path: Path) -> frozenset[str] | None:
83
+ """Return the fingerprints listed in a baseline file.
84
+
85
+ Returns ``None`` when the file does not exist. Raises ``BaselineError``
86
+ when it exists but cannot be read or understood: guessing would either
87
+ hide new problems or bring back all the old ones.
88
+ """
89
+ if not path.is_file():
90
+ return None
91
+ try:
92
+ document: Any = json.loads(path.read_text(encoding="utf-8"))
93
+ except OSError as error:
94
+ raise BaselineError(f"{path}: cannot be read: {error}") from error
95
+ except ValueError as error:
96
+ raise BaselineError(f"{path}: not valid JSON: {error}") from error
97
+
98
+ if not isinstance(document, dict):
99
+ raise BaselineError(f"{path}: not a SecureLint baseline file")
100
+ if document.get("format_version") != BASELINE_FORMAT_VERSION:
101
+ raise BaselineError(
102
+ f"{path}: written in a format this version of SecureLint does not "
103
+ "read; run `securelint baseline` to write it again"
104
+ )
105
+ entries = document.get("findings")
106
+ if not isinstance(entries, list):
107
+ raise BaselineError(f"{path}: not a SecureLint baseline file")
108
+
109
+ fingerprints = set()
110
+ for entry in entries:
111
+ fingerprint = entry.get("fingerprint") if isinstance(entry, dict) else None
112
+ if not isinstance(fingerprint, str) or not fingerprint:
113
+ raise BaselineError(f"{path}: an entry has no fingerprint")
114
+ fingerprints.add(fingerprint)
115
+ return frozenset(fingerprints)
116
+
117
+
118
+ def split_known(result: ScanResult, known: frozenset[str]) -> ScanResult:
119
+ """Move the findings listed in the baseline out of ``result.findings``.
120
+
121
+ They are kept in ``result.known``, so reports can still show them.
122
+ """
123
+ return replace(
124
+ result,
125
+ findings=tuple(f for f in result.findings if f.fingerprint not in known),
126
+ known=tuple(f for f in result.findings if f.fingerprint in known),
127
+ )
128
+
129
+
130
+ def count_no_longer_found(result: ScanResult, known: frozenset[str]) -> int:
131
+ """Return how many baseline entries match nothing in a scan result.
132
+
133
+ Each one is a known problem that was fixed, or whose line was edited.
134
+ Only meaningful for a scan of the whole project.
135
+ """
136
+ present = {finding.fingerprint for finding in result.findings}
137
+ present.update(finding.fingerprint for finding in result.known)
138
+ present.update(item.finding.fingerprint for item in result.silenced)
139
+ return len(known - present)
securelint/cache.py ADDED
@@ -0,0 +1,103 @@
1
+ """Remember explanations, so the same finding is not paid for twice.
2
+
3
+ An explanation is kept under a fingerprint of everything that was sent for
4
+ it: the provider, the model and the whole prompt (the rule, the message and
5
+ the masked lines around the finding). The same question gets the same
6
+ answer back; a change in any of them, such as an edited line nearby or
7
+ another model, asks the AI again.
8
+
9
+ The cache lives in ``.securelint-cache/`` at the top of the project, with a
10
+ ``.gitignore`` of its own so it is never committed. It holds the
11
+ explanations and their fingerprints, never any code.
12
+
13
+ A cache is a convenience: one that cannot be read starts empty, and one
14
+ that cannot be written is only reported. Neither changes a scan.
15
+ """
16
+
17
+ import hashlib
18
+ import json
19
+ from pathlib import Path
20
+
21
+ from securelint.prompt import Prompt
22
+
23
+ CACHE_FOLDER = ".securelint-cache"
24
+ _FILE_NAME = "explanations.json"
25
+ _FORMAT_VERSION = 1
26
+
27
+ MAX_ENTRIES = 1000
28
+ """Explanations kept at most; the oldest go first."""
29
+
30
+
31
+ class ExplanationCache:
32
+ """The explanations of one project, for one provider and model."""
33
+
34
+ def __init__(self, folder: Path, scope: str) -> None:
35
+ """Open the cache in ``folder``. ``scope`` names the provider and
36
+ model, so their explanations are never mixed with another's."""
37
+ self.folder = folder
38
+ self.scope = scope
39
+ self.problem: str | None = None
40
+ """Why the saved cache could not be used, if it could not."""
41
+ self.entries = self._load()
42
+ self.changed = False
43
+ self.hits = 0
44
+ """How many explanations were found in the cache."""
45
+
46
+ def get(self, prompt: Prompt) -> str | None:
47
+ """Return the explanation kept for ``prompt``, if there is one."""
48
+ explanation = self.entries.get(self._key(prompt))
49
+ if explanation is not None:
50
+ self.hits += 1
51
+ return explanation
52
+
53
+ def put(self, prompt: Prompt, explanation: str) -> None:
54
+ """Keep ``explanation`` as the answer to ``prompt``."""
55
+ key = self._key(prompt)
56
+ # Put back at the end: the newest entries are the last to go.
57
+ self.entries.pop(key, None)
58
+ self.entries[key] = explanation
59
+ while len(self.entries) > MAX_ENTRIES:
60
+ del self.entries[next(iter(self.entries))]
61
+ self.changed = True
62
+
63
+ def save(self) -> str | None:
64
+ """Write the cache if it changed; return why it failed, if it did."""
65
+ if not self.changed:
66
+ return None
67
+ document = {"format_version": _FORMAT_VERSION, "entries": self.entries}
68
+ try:
69
+ self.folder.mkdir(exist_ok=True)
70
+ ignore = self.folder / ".gitignore"
71
+ if not ignore.exists():
72
+ ignore.write_text("# Made by SecureLint.\n*\n", encoding="utf-8")
73
+ # Written beside, then put in place in one step, so a scan that
74
+ # stops halfway never leaves half a file.
75
+ path = self.folder / _FILE_NAME
76
+ partial = path.with_suffix(".tmp")
77
+ partial.write_text(json.dumps(document, indent=1), encoding="utf-8")
78
+ partial.replace(path)
79
+ except OSError as error:
80
+ return f"cannot save the explanation cache: {error}"
81
+ self.changed = False
82
+ return None
83
+
84
+ def _key(self, prompt: Prompt) -> str:
85
+ parts = [self.scope, prompt.system, prompt.user]
86
+ return hashlib.sha256("\0".join(parts).encode()).hexdigest()
87
+
88
+ def _load(self) -> dict[str, str]:
89
+ path = self.folder / _FILE_NAME
90
+ if not path.exists():
91
+ return {}
92
+ try:
93
+ document = json.loads(path.read_text(encoding="utf-8"))
94
+ entries = document["entries"]
95
+ if document["format_version"] != _FORMAT_VERSION or not all(
96
+ isinstance(key, str) and isinstance(text, str)
97
+ for key, text in entries.items()
98
+ ):
99
+ raise ValueError("unexpected content")
100
+ except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
101
+ self.problem = f"the explanation cache was not used: {error}"
102
+ return {}
103
+ return dict(entries)
securelint/changes.py ADDED
@@ -0,0 +1,250 @@
1
+ """Find the lines a change touched, by asking Git.
2
+
3
+ ``securelint scan --changed-since main`` reports only the findings on lines
4
+ that the current branch added or changed since it left ``main``. A
5
+ developer who edits one function then hears about that function, not
6
+ about everything else in the file.
7
+
8
+ "Changed" means: compared with the commit where the branch left ``main``
9
+ (Git's merge base), including changes not yet committed. A file Git does
10
+ not track yet counts as changed in full.
11
+
12
+ Git is run as a separate program with a fixed list of arguments, never
13
+ through a shell. The branch name comes from the command line, so a name
14
+ starting with ``-`` is refused: Git would read it as an option.
15
+ """
16
+
17
+ import re
18
+ import shutil
19
+ import subprocess
20
+ from collections.abc import Mapping, Sequence
21
+ from dataclasses import dataclass, replace
22
+ from pathlib import Path
23
+
24
+ from securelint.engine import ScanResult
25
+ from securelint.model import Finding
26
+
27
+ # "@@ -12,3 +12,4 @@": 3 old lines from line 12 became 4 new lines from
28
+ # line 12. A count left out means 1.
29
+ _HUNK = re.compile(rb"^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
30
+
31
+ _TIMEOUT_SECONDS = 60
32
+
33
+ # Git writes unusual characters in file names the way C strings do.
34
+ _ESCAPES = {
35
+ ord("a"): b"\a",
36
+ ord("b"): b"\b",
37
+ ord("f"): b"\f",
38
+ ord("n"): b"\n",
39
+ ord("r"): b"\r",
40
+ ord("t"): b"\t",
41
+ ord("v"): b"\v",
42
+ }
43
+
44
+
45
+ class ChangesError(Exception):
46
+ """The changed lines cannot be found; the message says why."""
47
+
48
+
49
+ @dataclass(frozen=True, slots=True)
50
+ class ChangedLines:
51
+ """The lines a change touched, file by file."""
52
+
53
+ base: str
54
+ """The branch or commit the change is compared with, as given."""
55
+
56
+ merge_base: str
57
+ """The commit where the current branch left ``base``."""
58
+
59
+ files: Mapping[Path, frozenset[int] | None]
60
+ """For each changed file, as a full path: the changed line numbers, or
61
+ ``None`` when the whole file is new."""
62
+
63
+ def contains(self, path: Path, line: int) -> bool:
64
+ """Return True if ``line`` of the file at ``path`` (a full path) changed."""
65
+ if path not in self.files:
66
+ return False
67
+ lines = self.files[path]
68
+ return lines is None or line in lines
69
+
70
+
71
+ def find_changed_lines(place: Path, base: str) -> ChangedLines:
72
+ """Return the lines changed since the current branch left ``base``.
73
+
74
+ ``place`` is any path inside the Git repository.
75
+
76
+ Raises ``ChangesError`` when Git is missing, ``place`` is not in a Git
77
+ repository, or ``base`` cannot be found. Reporting nothing in those
78
+ cases would look like a clean change.
79
+ """
80
+ if not base or base.startswith("-"):
81
+ raise ChangesError(f"{base!r} is not a branch or commit name")
82
+ git = shutil.which("git")
83
+ if git is None:
84
+ raise ChangesError("--changed-since needs Git, which was not found")
85
+
86
+ start = place.resolve()
87
+ if not start.is_dir():
88
+ start = start.parent
89
+ top_output = _git(
90
+ git,
91
+ start,
92
+ ["rev-parse", "--show-toplevel"],
93
+ "--changed-since needs a Git repository",
94
+ )
95
+ top = Path(top_output.decode("utf-8", "surrogateescape").strip()).resolve()
96
+
97
+ merge_base = (
98
+ _git(
99
+ git,
100
+ top,
101
+ ["merge-base", base, "HEAD"],
102
+ # A shallow copy of a repository (GitHub Actions' default) does
103
+ # not hold the commit where the branch started.
104
+ f"cannot find where this branch left {base!r} (in GitHub Actions, "
105
+ "check out the whole history with fetch-depth: 0)",
106
+ )
107
+ .decode("ascii", "replace")
108
+ .strip()
109
+ )
110
+
111
+ diff = _git(
112
+ git,
113
+ top,
114
+ [
115
+ "-c",
116
+ "core.quotepath=off",
117
+ "diff",
118
+ # Fixed choices, so the user's own Git settings cannot change
119
+ # the layout of what is read below.
120
+ "--no-color",
121
+ "--no-ext-diff",
122
+ "--no-textconv",
123
+ "--no-relative",
124
+ "--find-renames",
125
+ "--src-prefix=a/",
126
+ "--dst-prefix=b/",
127
+ "--unified=0",
128
+ merge_base,
129
+ ],
130
+ "cannot list the changed lines",
131
+ )
132
+ files: dict[Path, frozenset[int] | None] = {
133
+ path: frozenset(lines) for path, lines in _parse_diff(diff, top).items()
134
+ }
135
+
136
+ untracked = _git(
137
+ git,
138
+ top,
139
+ ["ls-files", "--others", "--exclude-standard", "-z"],
140
+ "cannot list the new files",
141
+ )
142
+ for name in untracked.split(b"\0"):
143
+ if name:
144
+ path = top / name.decode("utf-8", "surrogateescape")
145
+ files[path.resolve()] = None
146
+
147
+ return ChangedLines(base=base, merge_base=merge_base, files=files)
148
+
149
+
150
+ def split_outside_change(
151
+ result: ScanResult, changes: ChangedLines, target: Path
152
+ ) -> ScanResult:
153
+ """Move the findings on lines the change did not touch out of ``findings``.
154
+
155
+ They are kept in ``result.outside_change``, so reports can count them.
156
+ ``target`` is the file or directory that was scanned.
157
+ """
158
+ directory = target.resolve()
159
+ if not directory.is_dir():
160
+ directory = directory.parent
161
+
162
+ def touched(finding: Finding) -> bool:
163
+ return changes.contains((directory / finding.path).resolve(), finding.line)
164
+
165
+ return replace(
166
+ result,
167
+ findings=tuple(f for f in result.findings if touched(f)),
168
+ outside_change=tuple(f for f in result.findings if not touched(f)),
169
+ )
170
+
171
+
172
+ def _parse_diff(diff: bytes, top: Path) -> dict[Path, set[int]]:
173
+ """Read ``git diff --unified=0`` output: the new line numbers of each file."""
174
+ files: dict[Path, set[int]] = {}
175
+ current: set[int] | None = None
176
+ # Lines of the current hunk still to come. They are skipped by count,
177
+ # so an added line that happens to start with "++ " is never mistaken
178
+ # for the "+++ " line that names a file.
179
+ remaining = 0
180
+ for raw in diff.split(b"\n"):
181
+ if remaining:
182
+ if raw.startswith((b"+", b"-", b" ")):
183
+ remaining -= 1
184
+ continue
185
+ if raw.startswith(b"\\"):
186
+ # "" is not a line of the file.
187
+ continue
188
+ remaining = 0
189
+
190
+ if raw.startswith(b"+++ "):
191
+ name = raw[4:]
192
+ if name == b"/dev/null":
193
+ # The file was deleted: none of its lines exist any more.
194
+ current = None
195
+ continue
196
+ path_text = _unquote(name).removeprefix("b/")
197
+ current = files.setdefault((top / path_text).resolve(), set())
198
+ continue
199
+
200
+ match = _HUNK.match(raw)
201
+ if match is not None and current is not None:
202
+ old_count = int(match[1]) if match[1] is not None else 1
203
+ start = int(match[2])
204
+ new_count = int(match[3]) if match[3] is not None else 1
205
+ current.update(range(start, start + new_count))
206
+ remaining = old_count + new_count
207
+ return files
208
+
209
+
210
+ def _unquote(name: bytes) -> str:
211
+ """Return a file name as Git wrote it, without its quotes and escapes."""
212
+ if len(name) >= 2 and name.startswith(b'"') and name.endswith(b'"'):
213
+ data = name[1:-1]
214
+ decoded = bytearray()
215
+ index = 0
216
+ while index < len(data):
217
+ byte = data[index]
218
+ if byte == ord("\\") and index + 1 < len(data):
219
+ following = data[index + 1]
220
+ octal = data[index + 1 : index + 4]
221
+ if len(octal) == 3 and all(ord("0") <= b <= ord("7") for b in octal):
222
+ decoded.append(int(octal, 8))
223
+ index += 4
224
+ continue
225
+ decoded += _ESCAPES.get(following, bytes([following]))
226
+ index += 2
227
+ continue
228
+ decoded.append(byte)
229
+ index += 1
230
+ name = bytes(decoded)
231
+ return name.decode("utf-8", "surrogateescape")
232
+
233
+
234
+ def _git(git: str, cwd: Path, arguments: Sequence[str], problem: str) -> bytes:
235
+ """Run Git and return what it wrote; raise ``ChangesError`` if it failed."""
236
+ try:
237
+ completed = subprocess.run( # noqa: S603 (Git, a list of arguments, no shell)
238
+ [git, *arguments],
239
+ cwd=cwd,
240
+ capture_output=True,
241
+ check=False,
242
+ timeout=_TIMEOUT_SECONDS,
243
+ )
244
+ except (OSError, subprocess.TimeoutExpired) as error:
245
+ raise ChangesError(f"{problem}: Git could not be run ({error})") from error
246
+ if completed.returncode != 0:
247
+ details = completed.stderr.decode("utf-8", "replace").strip().splitlines()
248
+ reason = details[-1] if details else f"Git exit code {completed.returncode}"
249
+ raise ChangesError(f"{problem}: {reason}")
250
+ return completed.stdout