worktree-shield 0.1.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.
- worktree_shield/__init__.py +8 -0
- worktree_shield/__main__.py +6 -0
- worktree_shield/cli.py +377 -0
- worktree_shield/collectors/__init__.py +1 -0
- worktree_shield/collectors/base.py +63 -0
- worktree_shield/collectors/compose.py +315 -0
- worktree_shield/collectors/envfiles.py +130 -0
- worktree_shield/collectors/layout.py +106 -0
- worktree_shield/collectors/node.py +87 -0
- worktree_shield/collectors/procfile.py +134 -0
- worktree_shield/collectors/python.py +128 -0
- worktree_shield/collectors/runtime.py +167 -0
- worktree_shield/collectors/static.py +25 -0
- worktree_shield/collectors/vite.py +133 -0
- worktree_shield/collisions.py +115 -0
- worktree_shield/config.py +188 -0
- worktree_shield/exit_codes.py +22 -0
- worktree_shield/files.py +70 -0
- worktree_shield/git/__init__.py +1 -0
- worktree_shield/git/discovery.py +85 -0
- worktree_shield/git/porcelain.py +48 -0
- worktree_shield/models.py +356 -0
- worktree_shield/names.py +83 -0
- worktree_shield/orchestrator.py +121 -0
- worktree_shield/overlap.py +175 -0
- worktree_shield/parsers/__init__.py +1 -0
- worktree_shield/parsers/commands.py +158 -0
- worktree_shield/parsers/compose.py +148 -0
- worktree_shield/parsers/dburl.py +156 -0
- worktree_shield/parsers/dotenv.py +91 -0
- worktree_shield/parsers/interpolate.py +142 -0
- worktree_shield/parsers/jsonc.py +48 -0
- worktree_shield/parsers/jstext.py +142 -0
- worktree_shield/plan.py +175 -0
- worktree_shield/privacy.py +237 -0
- worktree_shield/reports/__init__.py +1 -0
- worktree_shield/reports/findings.py +176 -0
- worktree_shield/reports/json_report.py +61 -0
- worktree_shield/reports/markdown.py +103 -0
- worktree_shield/reports/sarif.py +116 -0
- worktree_shield/reports/terminal.py +327 -0
- worktree_shield/rules/__init__.py +1 -0
- worktree_shield/rules/catalog.py +28 -0
- worktree_shield/rules/common.py +61 -0
- worktree_shield/rules/context.py +201 -0
- worktree_shield/rules/engine.py +60 -0
- worktree_shield/rules/explain.py +27 -0
- worktree_shield/rules/rules.md +112 -0
- worktree_shield/rules/runtime.py +164 -0
- worktree_shield/rules/shared.py +216 -0
- worktree_shield/runner.py +273 -0
- worktree_shield-0.1.0.dist-info/METADATA +151 -0
- worktree_shield-0.1.0.dist-info/RECORD +56 -0
- worktree_shield-0.1.0.dist-info/WHEEL +4 -0
- worktree_shield-0.1.0.dist-info/entry_points.txt +4 -0
- worktree_shield-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
"""Rules about what the scan could and could not see, and about the policy itself."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterator
|
|
6
|
+
|
|
7
|
+
from worktree_shield.collectors.envfiles import NOT_READ
|
|
8
|
+
from worktree_shield.models import (
|
|
9
|
+
Confidence,
|
|
10
|
+
Evidence,
|
|
11
|
+
Finding,
|
|
12
|
+
Observation,
|
|
13
|
+
ResourceKind,
|
|
14
|
+
Severity,
|
|
15
|
+
Status,
|
|
16
|
+
)
|
|
17
|
+
from worktree_shield.rules.common import evidence, plain, plural, port_of, where
|
|
18
|
+
from worktree_shield.rules.engine import Context, Rule
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _unreadable_databases(context: Context) -> Iterator[Finding]:
|
|
22
|
+
values = [v for v in context.snapshot.unreadable if v.kind is ResourceKind.DATABASE]
|
|
23
|
+
for value in values:
|
|
24
|
+
yield Finding(
|
|
25
|
+
"WTS-DB-002",
|
|
26
|
+
Status.UNKNOWN,
|
|
27
|
+
Severity.MEDIUM,
|
|
28
|
+
Confidence.MEDIUM,
|
|
29
|
+
f"{value.name} in {where(value.source)} names a database that could not be identified",
|
|
30
|
+
f"The URL {value.reason}. A collision on this database can be neither "
|
|
31
|
+
"confirmed nor ruled out; its value is not shown.",
|
|
32
|
+
worktrees=(value.source.worktree,),
|
|
33
|
+
sources=(value.source,),
|
|
34
|
+
recommended_action="Percent-encode special characters in the password (/ is %2F, "
|
|
35
|
+
"# is %23, ? is %3F) and spell the host out.",
|
|
36
|
+
verify_command="worktree-shield resources",
|
|
37
|
+
)
|
|
38
|
+
if values:
|
|
39
|
+
return
|
|
40
|
+
if any(c.kind is ResourceKind.DATABASE for c in context.snapshot.claims):
|
|
41
|
+
yield plain(
|
|
42
|
+
"WTS-DB-002",
|
|
43
|
+
Status.PASS,
|
|
44
|
+
"Every database URL could be identified",
|
|
45
|
+
"No database URL was refused.",
|
|
46
|
+
)
|
|
47
|
+
else:
|
|
48
|
+
yield plain(
|
|
49
|
+
"WTS-DB-002",
|
|
50
|
+
Status.NOT_APPLICABLE,
|
|
51
|
+
"No database URL was found",
|
|
52
|
+
"Nothing of this kind was found in the configuration.",
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _unread_configuration(context: Context) -> Iterator[Finding]:
|
|
57
|
+
skipped = [s for s in context.snapshot.skipped if s.reason != NOT_READ]
|
|
58
|
+
values = [v for v in context.snapshot.unreadable if v.kind is not ResourceKind.DATABASE]
|
|
59
|
+
items = [Evidence(where(s.source), s.source.worktree, s.reason) for s in skipped]
|
|
60
|
+
items += [Evidence(where(v.source), v.source.worktree, f"{v.name} {v.reason}") for v in values]
|
|
61
|
+
if not items:
|
|
62
|
+
yield plain(
|
|
63
|
+
"WTS-CONFIG-001",
|
|
64
|
+
Status.PASS,
|
|
65
|
+
"Every configuration file found was read",
|
|
66
|
+
"No file was refused and every value could be identified.",
|
|
67
|
+
)
|
|
68
|
+
return
|
|
69
|
+
worktrees = tuple(dict.fromkeys(item.key for item in items))
|
|
70
|
+
yield Finding(
|
|
71
|
+
"WTS-CONFIG-001",
|
|
72
|
+
Status.UNKNOWN,
|
|
73
|
+
Severity.LOW,
|
|
74
|
+
Confidence.MEDIUM,
|
|
75
|
+
f"{plural(len(items), 'configuration item')} could not be read",
|
|
76
|
+
"A file that was not read, or a value that could not be identified, can hide a collision.",
|
|
77
|
+
worktrees=worktrees,
|
|
78
|
+
sources=tuple(s.source for s in skipped) + tuple(v.source for v in values),
|
|
79
|
+
evidence=tuple(items),
|
|
80
|
+
recommended_action="Fix the files listed (or raise scan.max_file_bytes for large "
|
|
81
|
+
"ones), then scan again.",
|
|
82
|
+
verify_command="worktree-shield resources",
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _env_files(context: Context) -> Iterator[Finding]:
|
|
87
|
+
unread = [s for s in context.snapshot.skipped if s.reason == NOT_READ]
|
|
88
|
+
if unread:
|
|
89
|
+
worktrees = tuple(dict.fromkeys(s.source.worktree for s in unread))
|
|
90
|
+
yield Finding(
|
|
91
|
+
"WTS-ENV-001",
|
|
92
|
+
Status.UNKNOWN,
|
|
93
|
+
Severity.LOW,
|
|
94
|
+
Confidence.MEDIUM,
|
|
95
|
+
f"{plural(len(unread), '.env file')} {'was' if len(unread) == 1 else 'were'} not read",
|
|
96
|
+
"What runs may differ from what was read: a .env can set another port or "
|
|
97
|
+
"database than the templates, which would make a finding wrong or miss one.",
|
|
98
|
+
worktrees=worktrees,
|
|
99
|
+
sources=tuple(s.source for s in unread),
|
|
100
|
+
evidence=tuple(
|
|
101
|
+
Evidence(where(s.source), s.source.worktree, "not read") for s in unread
|
|
102
|
+
),
|
|
103
|
+
recommended_action="Scan with --include-env (or include_env_files = true); only "
|
|
104
|
+
"ports, database servers and paths are kept from them.",
|
|
105
|
+
verify_command="worktree-shield scan --include-env",
|
|
106
|
+
)
|
|
107
|
+
elif context.policy.include_env_files:
|
|
108
|
+
yield plain(
|
|
109
|
+
"WTS-ENV-001",
|
|
110
|
+
Status.PASS,
|
|
111
|
+
".env files were read",
|
|
112
|
+
"The scan included .env and .env.local.",
|
|
113
|
+
)
|
|
114
|
+
else:
|
|
115
|
+
yield plain(
|
|
116
|
+
"WTS-ENV-001",
|
|
117
|
+
Status.NOT_APPLICABLE,
|
|
118
|
+
"No .env files were found",
|
|
119
|
+
"No worktree has a .env or .env.local.",
|
|
120
|
+
)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def _prunable(context: Context) -> Iterator[Finding]:
|
|
124
|
+
repository = context.snapshot.repository
|
|
125
|
+
gone = [w for w in repository.worktrees if w.prunable is not None] if repository else []
|
|
126
|
+
for worktree in gone:
|
|
127
|
+
yield Finding(
|
|
128
|
+
"WTS-GIT-002",
|
|
129
|
+
Status.WARN,
|
|
130
|
+
Severity.INFO,
|
|
131
|
+
Confidence.HIGH,
|
|
132
|
+
f"The worktree {worktree.path} is listed by Git but its directory is gone",
|
|
133
|
+
"Git keeps the record until it is pruned; nothing there can collide, and it was "
|
|
134
|
+
"not scanned." + (f" Git says: {worktree.prunable}." if worktree.prunable else ""),
|
|
135
|
+
worktrees=(worktree.path,),
|
|
136
|
+
recommended_action="If it is gone for good, git worktree prune removes the record; "
|
|
137
|
+
"worktree-shield never prunes.",
|
|
138
|
+
verify_command="git worktree list",
|
|
139
|
+
)
|
|
140
|
+
if not gone:
|
|
141
|
+
yield plain(
|
|
142
|
+
"WTS-GIT-002", Status.PASS, "Every listed worktree exists", "No worktree is prunable."
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _policy_contradictions(context: Context) -> Iterator[Finding]:
|
|
147
|
+
policy = context.policy
|
|
148
|
+
if not policy.allow_ports and not policy.allow_paths:
|
|
149
|
+
yield plain(
|
|
150
|
+
"WTS-POLICY-001",
|
|
151
|
+
Status.NOT_APPLICABLE,
|
|
152
|
+
"The policy allows nothing explicitly",
|
|
153
|
+
"There are no [allow] entries to check.",
|
|
154
|
+
)
|
|
155
|
+
return
|
|
156
|
+
listening = [
|
|
157
|
+
c
|
|
158
|
+
for c in context.snapshot.claims
|
|
159
|
+
if c.kind is ResourceKind.LISTEN_PORT and c.observation is Observation.STATIC
|
|
160
|
+
]
|
|
161
|
+
found = False
|
|
162
|
+
for port in policy.allow_ports:
|
|
163
|
+
claims = [c for c in listening if port_of(c.key) == port]
|
|
164
|
+
if not claims:
|
|
165
|
+
continue
|
|
166
|
+
found = True
|
|
167
|
+
where_set = f" in {policy.source}" if policy.source else ""
|
|
168
|
+
yield Finding(
|
|
169
|
+
"WTS-POLICY-001",
|
|
170
|
+
Status.WARN,
|
|
171
|
+
Severity.LOW,
|
|
172
|
+
Confidence.HIGH,
|
|
173
|
+
f"[allow] ports lists {port}, which the worktrees listen on",
|
|
174
|
+
"[allow] ports covers servers the worktrees connect to, such as one shared "
|
|
175
|
+
"database; it never lets two servers listen on one port, so WTS-PORT-001 still "
|
|
176
|
+
"applies to it.",
|
|
177
|
+
worktrees=tuple(dict.fromkeys(c.worktree for c in claims)),
|
|
178
|
+
sources=tuple(c.source for c in claims),
|
|
179
|
+
evidence=evidence(claims),
|
|
180
|
+
recommended_action=f"Remove {port} from [allow] ports{where_set}, or give each "
|
|
181
|
+
"worktree its own port.",
|
|
182
|
+
verify_command="worktree-shield policy",
|
|
183
|
+
)
|
|
184
|
+
if not found:
|
|
185
|
+
yield plain(
|
|
186
|
+
"WTS-POLICY-001",
|
|
187
|
+
Status.PASS,
|
|
188
|
+
"The policy matches the configuration",
|
|
189
|
+
"No [allow] entry contradicts what the worktrees configure.",
|
|
190
|
+
)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
RULES = (
|
|
194
|
+
Rule("WTS-DB-002", "A database URL that could not be identified safely", _unreadable_databases),
|
|
195
|
+
Rule("WTS-CONFIG-001", "Configuration that could not be read", _unread_configuration),
|
|
196
|
+
Rule("WTS-ENV-001", ".env files the scan did not read", _env_files),
|
|
197
|
+
Rule("WTS-GIT-002", "A worktree Git lists whose directory is gone", _prunable),
|
|
198
|
+
Rule(
|
|
199
|
+
"WTS-POLICY-001", "An [allow] entry the configuration contradicts", _policy_contradictions
|
|
200
|
+
),
|
|
201
|
+
)
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Rules, how they are run, and how a policy level and a certainty become a status."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Callable, Iterable, Sequence
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
|
|
8
|
+
from worktree_shield.collisions import find_collisions
|
|
9
|
+
from worktree_shield.models import (
|
|
10
|
+
Certainty,
|
|
11
|
+
Collision,
|
|
12
|
+
Confidence,
|
|
13
|
+
Finding,
|
|
14
|
+
Policy,
|
|
15
|
+
PolicyLevel,
|
|
16
|
+
Snapshot,
|
|
17
|
+
Status,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True, slots=True)
|
|
22
|
+
class Context:
|
|
23
|
+
"""What every rule sees: the snapshot, the effective policy and the collisions."""
|
|
24
|
+
|
|
25
|
+
snapshot: Snapshot
|
|
26
|
+
policy: Policy
|
|
27
|
+
collisions: tuple[Collision, ...] = field(default=())
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True, slots=True)
|
|
31
|
+
class Rule:
|
|
32
|
+
"""One WTS rule. ``title`` is the one-line description in ``rules list`` and the docs."""
|
|
33
|
+
|
|
34
|
+
id: str
|
|
35
|
+
title: str
|
|
36
|
+
check: Callable[[Context], Iterable[Finding]]
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def evaluate(snapshot: Snapshot, rules: Sequence[Rule]) -> tuple[Finding, ...]:
|
|
40
|
+
"""The findings of every rule, in catalog order."""
|
|
41
|
+
context = Context(snapshot, snapshot.policy or Policy(), find_collisions(snapshot.claims))
|
|
42
|
+
return tuple(finding for rule in rules for finding in rule.check(context))
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def status_for(level: PolicyLevel, certainty: Certainty) -> Status:
|
|
46
|
+
"""``deny`` fails what is confirmed or probable, ``warn`` warns, ``allow`` passes.
|
|
47
|
+
A possible collision only ever warns: failing CI on a guess helps nobody."""
|
|
48
|
+
if level is PolicyLevel.ALLOW:
|
|
49
|
+
return Status.PASS
|
|
50
|
+
if level is PolicyLevel.DENY and certainty in (Certainty.CONFIRMED, Certainty.PROBABLE):
|
|
51
|
+
return Status.FAIL
|
|
52
|
+
return Status.WARN
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def confidence_for(certainty: Certainty) -> Confidence:
|
|
56
|
+
if certainty is Certainty.CONFIRMED:
|
|
57
|
+
return Confidence.HIGH
|
|
58
|
+
if certainty is Certainty.PROBABLE:
|
|
59
|
+
return Confidence.MEDIUM
|
|
60
|
+
return Confidence.LOW
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""The explanation of each rule, from rules.md shipped with the package.
|
|
2
|
+
|
|
3
|
+
rules.md is a copy of docs/rules.md (a test keeps them identical), so ``explain``
|
|
4
|
+
prints exactly what the documentation says.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
from importlib.resources import files
|
|
11
|
+
|
|
12
|
+
_HEADING = re.compile(r"^## (WTS-[A-Z]+-\d{3}): .+$", re.M)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def rules_text() -> str:
|
|
16
|
+
return files("worktree_shield.rules").joinpath("rules.md").read_text(encoding="utf-8")
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def explanation(rule_id: str) -> str | None:
|
|
20
|
+
"""The section of a rule, heading included, or ``None`` for an unknown ID."""
|
|
21
|
+
text = rules_text()
|
|
22
|
+
headings = list(_HEADING.finditer(text))
|
|
23
|
+
for index, heading in enumerate(headings):
|
|
24
|
+
if heading.group(1) == rule_id.upper():
|
|
25
|
+
end = headings[index + 1].start() if index + 1 < len(headings) else len(text)
|
|
26
|
+
return text[heading.start() : end].strip() + "\n"
|
|
27
|
+
return None
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Rules
|
|
2
|
+
|
|
3
|
+
Every finding has a stable ID. CI pipelines and agents can rely on these IDs, so they never change meaning.
|
|
4
|
+
|
|
5
|
+
A finding's **status** comes from two things: the policy level for its kind of sharing (see
|
|
6
|
+
[policy.md](policy.md)) and the **certainty** of the collision:
|
|
7
|
+
|
|
8
|
+
| Level | Confirmed or probable | Possible |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `deny` | fail | warn |
|
|
11
|
+
| `warn` | warn | warn |
|
|
12
|
+
| `allow` | pass, with the reason | pass |
|
|
13
|
+
|
|
14
|
+
`--strict` exits with 1 when a finding fails. A *possible* collision never fails a run. Certainty is:
|
|
15
|
+
|
|
16
|
+
- **confirmed**: a running server, tied to a worktree by its working directory, holds the resource;
|
|
17
|
+
- **probable**: the configuration of two worktrees certainly names the same resource;
|
|
18
|
+
- **possible**: it depends on how a host name resolves, how a path is used, or Vite moving to the next free port.
|
|
19
|
+
|
|
20
|
+
A rule with nothing to look at is *not applicable*. Runtime rules are *not tested* when running processes were
|
|
21
|
+
not looked at (`--scope static`).
|
|
22
|
+
|
|
23
|
+
Outside a Git repository, `scan` exits with code 3 instead of reporting a finding.
|
|
24
|
+
|
|
25
|
+
## WTS-PORT-001: A listen port configured in more than one worktree
|
|
26
|
+
|
|
27
|
+
Two or more worktrees start a server on the same port and overlapping addresses: `*`, `0.0.0.0` and `::` take
|
|
28
|
+
every address. Only one server can listen at a time. Policy: `shared_host_ports` (default `deny`).
|
|
29
|
+
|
|
30
|
+
*Fix:* give each worktree its own port in its `.env`, or run one server at a time.
|
|
31
|
+
|
|
32
|
+
## WTS-PORT-002: A configured port already held by a running process
|
|
33
|
+
|
|
34
|
+
A port a worktree configures is in use right now. Either a server running in another worktree holds it
|
|
35
|
+
(confirmed), or a process outside the worktrees does, in which case the owner is shown if it is visible.
|
|
36
|
+
Policy: `shared_host_ports`.
|
|
37
|
+
|
|
38
|
+
*Fix:* stop the leftover server, or use another port.
|
|
39
|
+
|
|
40
|
+
## WTS-DB-001: A database used by more than one worktree
|
|
41
|
+
|
|
42
|
+
Two or more worktrees connect to the same database: the same engine, server, port and name. `localhost`,
|
|
43
|
+
`127.0.0.1` and `::1` count as one server. Migrations, seed data and tests of one worktree change the data of
|
|
44
|
+
the other. Policy: `shared_database` (default `warn`). A server whose port is listed in `[allow] ports` counts as
|
|
45
|
+
shared infrastructure, and its findings pass.
|
|
46
|
+
|
|
47
|
+
*Fix:* give each worktree its own database name.
|
|
48
|
+
|
|
49
|
+
## WTS-DB-002: A database URL that could not be identified safely
|
|
50
|
+
|
|
51
|
+
A variable holds a database URL whose server cannot be found with certainty. Examples: an unencoded `/`, `?` or
|
|
52
|
+
`#` in the password, a list of hosts, or `${DB_HOST}`. The value is never shown. Status: unknown.
|
|
53
|
+
|
|
54
|
+
*Fix:* percent-encode the password and spell out the host.
|
|
55
|
+
|
|
56
|
+
## WTS-DOCKER-001: A Compose project name shared by worktrees
|
|
57
|
+
|
|
58
|
+
The project name prefixes containers, networks and named volumes, so `docker compose up` in one worktree takes
|
|
59
|
+
over the other's stack. A `name:` in the compose file, or a compose file in a subdirectory such as `infra/`,
|
|
60
|
+
gives every worktree the same name. Policy: `shared_compose_projects` (default `warn`).
|
|
61
|
+
|
|
62
|
+
*Fix:* set `COMPOSE_PROJECT_NAME` per worktree, or drop `name:`.
|
|
63
|
+
|
|
64
|
+
## WTS-DOCKER-002: A fixed container name set in more than one worktree
|
|
65
|
+
|
|
66
|
+
A Docker daemon runs one container of a given name, so starting the second stack replaces the first or fails.
|
|
67
|
+
Policy: `fixed_container_names` (default `warn`).
|
|
68
|
+
|
|
69
|
+
*Fix:* remove `container_name`, or build it from `${COMPOSE_PROJECT_NAME}`.
|
|
70
|
+
|
|
71
|
+
## WTS-DOCKER-003: A Docker volume mounted in more than one worktree
|
|
72
|
+
|
|
73
|
+
The worktrees read and write the same data. When the volume is shared only because the project name is, the
|
|
74
|
+
finding follows from WTS-DOCKER-001. Policy: `shared_compose_projects`.
|
|
75
|
+
|
|
76
|
+
*Fix:* let Compose prefix the volume with the project name, or mark it external on purpose.
|
|
77
|
+
|
|
78
|
+
## WTS-PATH-001: An absolute path more than one worktree writes to
|
|
79
|
+
|
|
80
|
+
The same absolute directory, or one inside the other, is configured in two or more worktrees. Policy:
|
|
81
|
+
`shared_absolute_paths` (default `warn`). Paths at or below an entry of `[allow] paths` pass.
|
|
82
|
+
|
|
83
|
+
*Fix:* use a directory per worktree, or allow the path.
|
|
84
|
+
|
|
85
|
+
## WTS-ENV-001: .env files the scan did not read
|
|
86
|
+
|
|
87
|
+
`.env` and `.env.local` are read only with `--include-env`. A `.env` that was left out can set other ports or
|
|
88
|
+
databases than the templates, so a finding may be wrong or missing. Status: unknown.
|
|
89
|
+
|
|
90
|
+
*Fix:* scan with `--include-env`. Only ports, database servers and paths are kept.
|
|
91
|
+
|
|
92
|
+
## WTS-CONFIG-001: Configuration that could not be read
|
|
93
|
+
|
|
94
|
+
A file was refused (too large, invalid, a link out of the worktree), or a value could not be identified (for
|
|
95
|
+
example a port that depends on a variable no file sets). Any of these can hide a collision. Status: unknown.
|
|
96
|
+
|
|
97
|
+
## WTS-GIT-002: A worktree Git lists whose directory is gone
|
|
98
|
+
|
|
99
|
+
Nothing there can collide, and it was not scanned. worktree-shield never prunes it; `git worktree prune` does.
|
|
100
|
+
|
|
101
|
+
## WTS-RUNTIME-001: Running processes that could not be tied to a worktree
|
|
102
|
+
|
|
103
|
+
The runtime view was incomplete. Other users' processes are listed without their owner, and on macOS only the
|
|
104
|
+
current user's processes are visible. Collisions with what could not be seen cannot be ruled out. Status:
|
|
105
|
+
unknown.
|
|
106
|
+
|
|
107
|
+
## WTS-POLICY-001: An [allow] entry the configuration contradicts
|
|
108
|
+
|
|
109
|
+
`[allow] ports` lists a port the worktrees *listen* on. That entry covers servers the worktrees connect to; it
|
|
110
|
+
never lets two servers listen on one port, so WTS-PORT-001 still applies.
|
|
111
|
+
|
|
112
|
+
*Fix:* remove the entry, or give each worktree its own port.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""Rules about what is running now: ports held by servers or other processes."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterator
|
|
6
|
+
|
|
7
|
+
from worktree_shield.collectors.base import port_key
|
|
8
|
+
from worktree_shield.models import (
|
|
9
|
+
Certainty,
|
|
10
|
+
Confidence,
|
|
11
|
+
Finding,
|
|
12
|
+
Listener,
|
|
13
|
+
Observation,
|
|
14
|
+
ResourceKind,
|
|
15
|
+
Severity,
|
|
16
|
+
Status,
|
|
17
|
+
)
|
|
18
|
+
from worktree_shield.overlap import Overlap, overlap
|
|
19
|
+
from worktree_shield.rules.common import evidence, plain, port_of, verify_for
|
|
20
|
+
from worktree_shield.rules.engine import Context, Rule, confidence_for, status_for
|
|
21
|
+
|
|
22
|
+
NOT_LOOKED_AT = "Running processes were not looked at"
|
|
23
|
+
SNAPSHOT = "The running processes were looked at once, at the time of the scan."
|
|
24
|
+
_WHY_NOT = "The scan ran without the runtime observation (--no-runtime or include_runtime = false)."
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _ports_in_use(context: Context) -> Iterator[Finding]:
|
|
28
|
+
if context.snapshot.runtime is None:
|
|
29
|
+
yield plain(
|
|
30
|
+
"WTS-PORT-002",
|
|
31
|
+
Status.NOT_TESTED,
|
|
32
|
+
NOT_LOOKED_AT,
|
|
33
|
+
_WHY_NOT,
|
|
34
|
+
)
|
|
35
|
+
return
|
|
36
|
+
level = context.policy.shared_host_ports
|
|
37
|
+
found = False
|
|
38
|
+
for collision in context.collisions:
|
|
39
|
+
if (
|
|
40
|
+
collision.kind is not ResourceKind.LISTEN_PORT
|
|
41
|
+
or collision.certainty is not Certainty.CONFIRMED
|
|
42
|
+
):
|
|
43
|
+
continue
|
|
44
|
+
found = True
|
|
45
|
+
running = [c for c in collision.claims if c.observation is Observation.RUNTIME]
|
|
46
|
+
holders = ", ".join(dict.fromkeys(c.detail for c in running))
|
|
47
|
+
waiting = [c for c in collision.claims if c.worktree not in {r.worktree for r in running}]
|
|
48
|
+
yield Finding(
|
|
49
|
+
"WTS-PORT-002",
|
|
50
|
+
status_for(level, Certainty.CONFIRMED),
|
|
51
|
+
Severity.HIGH,
|
|
52
|
+
Confidence.HIGH,
|
|
53
|
+
f"Port {port_of(collision.key)} is in use by a server running in another worktree",
|
|
54
|
+
f"{holders}; {_configure(len({c.worktree for c in waiting}), 'other ')} the same "
|
|
55
|
+
"port, so their server cannot start while it runs.",
|
|
56
|
+
resource_key=collision.key,
|
|
57
|
+
certainty=Certainty.CONFIRMED,
|
|
58
|
+
worktrees=collision.worktrees,
|
|
59
|
+
sources=tuple(c.source for c in collision.claims),
|
|
60
|
+
evidence=evidence(collision.claims),
|
|
61
|
+
recommended_action="Stop the running server first, or start this worktree's "
|
|
62
|
+
"server on another port.",
|
|
63
|
+
verify_command=verify_for(collision.claims, context.policy),
|
|
64
|
+
limitations=(SNAPSHOT,),
|
|
65
|
+
)
|
|
66
|
+
static = [
|
|
67
|
+
c
|
|
68
|
+
for c in context.snapshot.claims
|
|
69
|
+
if c.kind is ResourceKind.LISTEN_PORT and c.observation is Observation.STATIC
|
|
70
|
+
]
|
|
71
|
+
by_port: dict[tuple[str, int], list[Listener]] = {}
|
|
72
|
+
for listener in context.snapshot.runtime.unattributed: # IPv4 and IPv6 sockets of one port
|
|
73
|
+
by_port.setdefault((listener.protocol, listener.port), []).append(listener)
|
|
74
|
+
for (protocol, port), listeners in by_port.items():
|
|
75
|
+
keys = [port_key(each.address, port, protocol=protocol) for each in listeners]
|
|
76
|
+
results = [
|
|
77
|
+
(claim, overlap(ResourceKind.LISTEN_PORT, key, claim.key))
|
|
78
|
+
for claim in static
|
|
79
|
+
for key in keys
|
|
80
|
+
]
|
|
81
|
+
blocked = list(dict.fromkeys(c for c, result in results if result is not Overlap.NONE))
|
|
82
|
+
if not blocked:
|
|
83
|
+
continue
|
|
84
|
+
found = True
|
|
85
|
+
certain = any(result is Overlap.SAME for _, result in results)
|
|
86
|
+
certainty = Certainty.CONFIRMED if certain else Certainty.POSSIBLE
|
|
87
|
+
worktrees = tuple(dict.fromkeys(c.worktree for c in blocked))
|
|
88
|
+
owners = "; ".join(dict.fromkeys(_owner(each) for each in listeners))
|
|
89
|
+
yield Finding(
|
|
90
|
+
"WTS-PORT-002",
|
|
91
|
+
status_for(level, certainty),
|
|
92
|
+
Severity.HIGH,
|
|
93
|
+
confidence_for(certainty),
|
|
94
|
+
f"Port {port} is already in use",
|
|
95
|
+
f"{owners}; {_configure(len(worktrees))} this port, so their server cannot start "
|
|
96
|
+
"while it does.",
|
|
97
|
+
resource_key=port_key(listeners[0].address, port, protocol=protocol),
|
|
98
|
+
certainty=certainty,
|
|
99
|
+
worktrees=worktrees,
|
|
100
|
+
sources=tuple(c.source for c in blocked),
|
|
101
|
+
evidence=evidence(blocked),
|
|
102
|
+
recommended_action="Stop that process if it is a leftover dev server, or give "
|
|
103
|
+
"the worktrees another port.",
|
|
104
|
+
verify_command=verify_for(blocked, context.policy),
|
|
105
|
+
limitations=(SNAPSHOT,),
|
|
106
|
+
)
|
|
107
|
+
if not found:
|
|
108
|
+
yield plain(
|
|
109
|
+
"WTS-PORT-002",
|
|
110
|
+
Status.PASS,
|
|
111
|
+
"No configured port is in use by another worktree or process",
|
|
112
|
+
"Every port the worktrees configure was free, as far as the runtime view shows.",
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _configure(count: int, other: str = "") -> str:
|
|
117
|
+
""" "1 worktree configures" or "3 worktrees configure"."""
|
|
118
|
+
return f"1 {other}worktree configures" if count == 1 else f"{count} {other}worktrees configure"
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _owner(listener: Listener) -> str:
|
|
122
|
+
"""Who listens, in a clause: "uvicorn (pid 42) listens on it; it runs outside …"."""
|
|
123
|
+
if listener.pid is None:
|
|
124
|
+
return "A process of another user listens on it"
|
|
125
|
+
name = listener.process or "A process"
|
|
126
|
+
return f"{name} (pid {listener.pid}) listens on it; {listener.note}"
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _runtime_view(context: Context) -> Iterator[Finding]:
|
|
130
|
+
runtime = context.snapshot.runtime
|
|
131
|
+
if runtime is None:
|
|
132
|
+
yield plain(
|
|
133
|
+
"WTS-RUNTIME-001",
|
|
134
|
+
Status.NOT_TESTED,
|
|
135
|
+
NOT_LOOKED_AT,
|
|
136
|
+
_WHY_NOT,
|
|
137
|
+
)
|
|
138
|
+
return
|
|
139
|
+
if runtime.limitations:
|
|
140
|
+
yield Finding(
|
|
141
|
+
"WTS-RUNTIME-001",
|
|
142
|
+
Status.UNKNOWN,
|
|
143
|
+
Severity.LOW,
|
|
144
|
+
Confidence.MEDIUM,
|
|
145
|
+
"Some running processes could not be tied to a worktree",
|
|
146
|
+
"The runtime view is incomplete: " + "; ".join(runtime.limitations) + ".",
|
|
147
|
+
recommended_action="Collisions with processes outside this view cannot be ruled "
|
|
148
|
+
"out; the static findings still apply.",
|
|
149
|
+
)
|
|
150
|
+
return
|
|
151
|
+
yield plain(
|
|
152
|
+
"WTS-RUNTIME-001",
|
|
153
|
+
Status.PASS,
|
|
154
|
+
"Every listening process was visible",
|
|
155
|
+
"No limitation of the runtime view was found.",
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
RULES = (
|
|
160
|
+
Rule("WTS-PORT-002", "A configured port already held by a running process", _ports_in_use),
|
|
161
|
+
Rule(
|
|
162
|
+
"WTS-RUNTIME-001", "Running processes that could not be tied to a worktree", _runtime_view
|
|
163
|
+
),
|
|
164
|
+
)
|