phiward 0.2.0b1__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.
- phiward/__init__.py +8 -0
- phiward/__main__.py +5 -0
- phiward/_toml.py +211 -0
- phiward/adapters/__init__.py +105 -0
- phiward/adapters/claude.py +429 -0
- phiward/broker.py +831 -0
- phiward/carryover.py +1613 -0
- phiward/claude_settings.py +1307 -0
- phiward/cli.py +110 -0
- phiward/config.py +936 -0
- phiward/confine.py +476 -0
- phiward/copying.py +533 -0
- phiward/core.py +105 -0
- phiward/data/agents-section.md +43 -0
- phiward/doctor.py +1132 -0
- phiward/fasthook.py +70 -0
- phiward/fsinfo.py +241 -0
- phiward/gateway.py +159 -0
- phiward/githooks.py +248 -0
- phiward/guards/__init__.py +0 -0
- phiward/guards/protected_paths.py +1138 -0
- phiward/hidden.py +281 -0
- phiward/init.py +155 -0
- phiward/install.py +828 -0
- phiward/inventory.py +173 -0
- phiward/mcp.py +186 -0
- phiward/mcp_config.py +1736 -0
- phiward/names.py +5 -0
- phiward/packs/dates.toml +17 -0
- phiward/packs/genomics.toml +51 -0
- phiward/packs/msk.toml +32 -0
- phiward/pathid.py +403 -0
- phiward/pathmatch.py +98 -0
- phiward/paths.py +942 -0
- phiward/pin.py +214 -0
- phiward/procinfo.py +73 -0
- phiward/remote.py +448 -0
- phiward/run.py +788 -0
- phiward/safeio.py +84 -0
- phiward/sanitize.py +691 -0
- phiward/selfcheck.py +1506 -0
- phiward/service.py +321 -0
- phiward/session_note.py +86 -0
- phiward/setup_cmd.py +886 -0
- phiward/shell.py +504 -0
- phiward/wholetool.py +1463 -0
- phiward-0.2.0b1.dist-info/METADATA +147 -0
- phiward-0.2.0b1.dist-info/RECORD +53 -0
- phiward-0.2.0b1.dist-info/WHEEL +5 -0
- phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
- phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
- phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
- phiward-0.2.0b1.dist-info/top_level.txt +1 -0
phiward/names.py
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
"""The program's names. phiward was called agent-guards before v0.2.0b1: the old program name is
|
|
2
|
+
kept as an alias for the beta, so every check that looks for the program looks for both."""
|
|
3
|
+
|
|
4
|
+
PROGRAMS = ("phiward", "agent-guards")
|
|
5
|
+
MODULES = ("phiward", "agent_guards")
|
phiward/packs/dates.toml
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Built-in sanitizer pack: dates and times (HIPAA treats dates tied to a person as identifiers).
|
|
2
|
+
# Off by default; turn it on with `[sanitize] packs = ["genomics", "dates"]`. Format: see
|
|
3
|
+
# packs/genomics.toml. Times are masked with their dates; a bare year is kept.
|
|
4
|
+
[pack]
|
|
5
|
+
name = "dates"
|
|
6
|
+
|
|
7
|
+
identifiers = [
|
|
8
|
+
# ISO 8601: 2024-03-05, 2024-03-05T14:22:01Z, 2024-03-05 14:22, 20240305T1422
|
|
9
|
+
'\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)? => <DATE>',
|
|
10
|
+
'\b\d{8}T\d{4,6}Z?\b => <DATE>',
|
|
11
|
+
# 03/05/2024, 3/5/24, 05.03.2024, 05-03-2024
|
|
12
|
+
'\b\d{1,2}[/.\-]\d{1,2}[/.\-](?:\d{4}|\d{2})\b => <DATE>',
|
|
13
|
+
# Mar 5 2024, 5 Mar 2024, March 5, 2024, and ls -l style "Mar 5 14:22" or "Mar 5 2024"
|
|
14
|
+
# (day first runs first, so "5 March 2024" is one date)
|
|
15
|
+
'(?i)\b\d{1,2}\s+(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?,?\s+\d{4} => <DATE>',
|
|
16
|
+
'(?i)\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+\d{1,2}(?:,?\s+\d{4}|\s+\d{1,2}:\d{2})?(?!\d) => <DATE>',
|
|
17
|
+
]
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Built-in sanitizer pack: generic genomics masks. Format of a pack file (also for packs you
|
|
2
|
+
# write yourself and name by path in `[sanitize] packs = ["path/to/pack.toml"]`):
|
|
3
|
+
#
|
|
4
|
+
# [pack]
|
|
5
|
+
# name = "..." optional, for humans
|
|
6
|
+
# paths = [ RULE, ... ] applied first, over all packs, before the identifier rules
|
|
7
|
+
# identifiers = [ RULE, ... ] applied in text mode AND table mode
|
|
8
|
+
# positions = [ RULE, ... ] text mode only (numbers and positions)
|
|
9
|
+
# keep_files = [ REGEX, ... ] whole file names that a <BAMFILE> rule leaves alone
|
|
10
|
+
#
|
|
11
|
+
# A RULE is 'REGEX => <PLACEHOLDER>': a Python regular expression, then " => ", then a
|
|
12
|
+
# placeholder in capitals between angle brackets. Write the regex as a TOML literal string
|
|
13
|
+
# ('...') so that backslashes stay as they are; for a quote character use \x27 or \x22.
|
|
14
|
+
# A rule that matches the empty string is refused. Rules run in file order. After all rules a
|
|
15
|
+
# second pass must change nothing, else the line is withheld.
|
|
16
|
+
[pack]
|
|
17
|
+
name = "genomics"
|
|
18
|
+
|
|
19
|
+
identifiers = [
|
|
20
|
+
# sequence and alignment file names (a path token ending in one), unless in keep_files;
|
|
21
|
+
# a match starts only where a token starts, so a long line stays linear
|
|
22
|
+
'(?i)(?<![^\s\x27\x22=,;()\[\]])[^\s\x27\x22=,;()\[\]]+\.(?:bam|cram|bai|crai|csi|sam|fastq|fq|bcf|vcf)(?:\.gz|\.bgz)?\b => <BAMFILE>',
|
|
23
|
+
# read names: Illumina and Casava colon forms (5 or more fields), with /1, #0, _UMI, +UMI tails;
|
|
24
|
+
# a match starts only where a word starts (leading `_ . -` are taken too), so a long word
|
|
25
|
+
# stays linear
|
|
26
|
+
'(?<![A-Za-z0-9_.\-])[_.\-]*[A-Za-z0-9](?:[A-Za-z0-9_\-]+(?:\.[A-Za-z0-9_\-]+)*)?(?::[A-Za-z0-9_\-]+(?:\.[A-Za-z0-9_\-]+)*){4,}(?:[/#+][A-Za-z0-9+\-]*)* => <READ>',
|
|
27
|
+
# PacBio movie names
|
|
28
|
+
'\bm\d{5}[A-Za-z]?_\d{6}_\d{6}/\d+(?:/\w+)? => <READ>',
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
positions = [
|
|
32
|
+
# chr1:123, 12:123456, chr2:1,234,567-1,300,000
|
|
33
|
+
'\b(?:[Cc]hr(?:\d{1,2}|[XYM]|MT)|\d{1,2}|X|Y|MT)\s*:\s*\d[\d,]*(?:\s*-\s*\d[\d,]*)? => <LOCUS>',
|
|
34
|
+
# chrX 12345
|
|
35
|
+
'\b(?:[Cc]hr(?:\d{1,2}|[XYM]|MT)|X|Y|MT)[\t ]+\d{3,} => <LOCUS>',
|
|
36
|
+
# 1_1234_A_C and chr7-55249071-C-T style variant IDs
|
|
37
|
+
'\b(?:[Cc]hr)?(?:\d{1,2}|X|Y|MT)[_.\-]\d{3,}(?:[_\-][ACGTN]+)+ => <LOCUS>',
|
|
38
|
+
# VCF-like rows: a chromosome cell, a tab, a position cell
|
|
39
|
+
'(?:^|(?<=\t))\d{1,2}\t\d{3,} => <LOCUS>',
|
|
40
|
+
# comma-grouped numbers of a million or more, then bare runs of five or more digits
|
|
41
|
+
'(?<![\d,])\d{1,3}(?:,\d{3}){2,}(?![\d,]) => <NUM>',
|
|
42
|
+
'(?<!\d)(?<!\d[.,])\d{5,}(?!\d)(?![.,]\d) => <NUM>',
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
# neutral work names: they carry no identity
|
|
46
|
+
keep_files = [
|
|
47
|
+
'slice\.bam(?:\.bai)?',
|
|
48
|
+
'rows(?:_b37)?\.vcf',
|
|
49
|
+
'b\d\d\.(?:bam|cram)(?:\.bai|\.crai|\.csi)?',
|
|
50
|
+
'b\d\d\.(?:bai|crai|csi)',
|
|
51
|
+
]
|
phiward/packs/msk.toml
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# EXAMPLE sanitizer pack: the identifier forms of one institution (MSK) and an example path
|
|
2
|
+
# layout. It is not a default; name it in the config to use it:
|
|
3
|
+
# [sanitize]
|
|
4
|
+
# packs = ["genomics", "msk"]
|
|
5
|
+
# Copy it and change the rules for another institution. The format is described at the top of
|
|
6
|
+
# genomics.toml.
|
|
7
|
+
#
|
|
8
|
+
# Two rules are examples of a project's folder layout, not facts about any institution:
|
|
9
|
+
# <PATIENTPATH> any path token holding inputs/patient
|
|
10
|
+
# <CLINICALPATH> any path token under /clinical/ (a made-up share of clinical data; change
|
|
11
|
+
# the prefix to your own)
|
|
12
|
+
# They run first (the `paths` list), so a clinical path is masked as a whole before a file-name
|
|
13
|
+
# rule sees it.
|
|
14
|
+
[pack]
|
|
15
|
+
name = "msk"
|
|
16
|
+
|
|
17
|
+
paths = [
|
|
18
|
+
'[^\s\x27\x22=,;()\[\]]*inputs/patient[^\s\x27\x22=,;()\[\]]* => <PATIENTPATH>',
|
|
19
|
+
'[^\s\x27\x22=,;()\[\]]*/clinical/[^\s\x27\x22=,;()\[\]]* => <CLINICALPATH>',
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
identifiers = [
|
|
23
|
+
# sample and patient IDs: P-0000000-T01-IM6 and forms like it
|
|
24
|
+
'\bP-\d{4,}(?:-[A-Za-z]\d{1,3})?(?:[-_][A-Za-z0-9]+)* => <SAMPLEID>',
|
|
25
|
+
# CMO IDs: C-ABC123-L001-d, s_C_ABC123_P001_d
|
|
26
|
+
'\bC-\w{6}(?:[-_]\w+)* => <CMOID>',
|
|
27
|
+
'\bs_C_\w+ => <CMOID>',
|
|
28
|
+
# anonymized BAM stems: AB123456-T
|
|
29
|
+
'\b[A-Z]{2}\d{6}-[A-Z]\b => <BAMID>',
|
|
30
|
+
# donor names
|
|
31
|
+
'\bDonor[\w\-]+|\bDONOR[\w\-]+ => <DONOR>',
|
|
32
|
+
]
|
phiward/pathid.py
ADDED
|
@@ -0,0 +1,403 @@
|
|
|
1
|
+
"""The canonical spelling and the identity of a path, from the file system itself.
|
|
2
|
+
|
|
3
|
+
A path can be written many ways that name the same file: through links, with `..`, in another
|
|
4
|
+
letter case or Unicode form (macOS), through the `/System/Volumes/Data` firmlink or as
|
|
5
|
+
`/.vol/<device>/<inode>` (macOS), through a bind mount (Linux). A check that computes the answer
|
|
6
|
+
from the written string misses some of them.
|
|
7
|
+
|
|
8
|
+
`walk(path)` asks the file system instead: it resolves the path part by part from folder
|
|
9
|
+
descriptors, as the kernel does, and returns the canonical spelling (macOS `F_GETPATH`, the form
|
|
10
|
+
Seatbelt matches; Linux `/proc/self/fd`) and the (device, inode) of every folder on the way.
|
|
11
|
+
`canon()` is its spelling; `fold()` is the key for deny comparisons (on macOS NFD and
|
|
12
|
+
case-folded; on Linux the path itself). A walk that blocks on a stale network mount blocks the
|
|
13
|
+
caller (a known limit: docs/threat-model.md).
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
import os
|
|
17
|
+
import stat
|
|
18
|
+
import sys
|
|
19
|
+
import unicodedata
|
|
20
|
+
from typing import List, NamedTuple, Optional, Tuple
|
|
21
|
+
|
|
22
|
+
_F_GETPATH = 50 # <sys/fcntl.h>
|
|
23
|
+
_O_EVTONLY = 0x8000 # macOS: open for event notification only (no read access needed)
|
|
24
|
+
MACOS = sys.platform == "darwin"
|
|
25
|
+
LINUX = sys.platform.startswith("linux")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def inside(path: str, folder: str, strict: bool = False) -> bool:
|
|
29
|
+
"""Whether `path` is `folder` or below it, as text (both absolute, in the same spelling);
|
|
30
|
+
`strict`: below it only. The one lexical rule for "inside": an empty or relative `folder` is
|
|
31
|
+
a caller's mistake (as text, "" would hold every absolute path), so it raises ValueError and
|
|
32
|
+
each caller says what a missing folder means for it."""
|
|
33
|
+
if not folder or not folder.startswith("/"):
|
|
34
|
+
raise ValueError(f"not an absolute folder: {folder!r}")
|
|
35
|
+
if path == folder:
|
|
36
|
+
return not strict
|
|
37
|
+
return path.startswith(folder.rstrip("/") + "/") or folder == "/" and path.startswith("/")
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def fold(path: str) -> str:
|
|
41
|
+
if MACOS:
|
|
42
|
+
return unicodedata.normalize("NFD", path).casefold()
|
|
43
|
+
return path
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _from_fd(fd: int) -> Optional[str]:
|
|
47
|
+
if MACOS:
|
|
48
|
+
import fcntl
|
|
49
|
+
try:
|
|
50
|
+
raw = fcntl.fcntl(fd, _F_GETPATH, b"\0" * 1024)
|
|
51
|
+
except OSError:
|
|
52
|
+
return None
|
|
53
|
+
return raw.split(b"\0", 1)[0].decode("utf-8", "surrogateescape") or None
|
|
54
|
+
if LINUX:
|
|
55
|
+
try:
|
|
56
|
+
return os.readlink(f"/proc/self/fd/{fd}")
|
|
57
|
+
except OSError:
|
|
58
|
+
return None
|
|
59
|
+
return None
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _dir_flags() -> int:
|
|
63
|
+
f = os.O_DIRECTORY | os.O_CLOEXEC | os.O_NOCTTY | os.O_NONBLOCK
|
|
64
|
+
if MACOS:
|
|
65
|
+
f |= _O_EVTONLY
|
|
66
|
+
elif LINUX:
|
|
67
|
+
f |= os.O_PATH # type: ignore[attr-defined]
|
|
68
|
+
return f
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
MAX_LINKS = 40
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class Walk(NamedTuple):
|
|
75
|
+
canon: str
|
|
76
|
+
ids: List[Tuple[int, int]] # (dev, ino) of every folder on the way, and of the last part
|
|
77
|
+
complete: bool # False: some part could not be resolved (callers fail closed)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _file_flags() -> int:
|
|
81
|
+
f = os.O_CLOEXEC | os.O_NOCTTY | os.O_NONBLOCK | os.O_NOFOLLOW
|
|
82
|
+
if MACOS:
|
|
83
|
+
f |= _O_EVTONLY
|
|
84
|
+
elif LINUX:
|
|
85
|
+
f |= os.O_PATH # type: ignore[attr-defined]
|
|
86
|
+
return f
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def walk_full(path: str) -> Walk:
|
|
90
|
+
"""Resolve an absolute path the way the kernel does, part by part:
|
|
91
|
+
each folder is opened from its parent's descriptor (`..` from the folder itself, links read
|
|
92
|
+
and followed in place), the last part is only looked up, never opened as a device. A part
|
|
93
|
+
that does not exist ends the walk normally: the rest is kept as text (with `.` and `..`
|
|
94
|
+
applied), and the walk is complete. Anything else that stops the walk (no permission, a
|
|
95
|
+
`/.vol` name that does not resolve, a magic link under `/proc`, too many links) makes it
|
|
96
|
+
incomplete: callers then treat the path as protected."""
|
|
97
|
+
if not (MACOS or LINUX):
|
|
98
|
+
return Walk(os.path.realpath(path), [], True)
|
|
99
|
+
flags = _dir_flags()
|
|
100
|
+
ids: List[Tuple[int, int]] = []
|
|
101
|
+
todo = [p for p in path.split("/") if p and p != "."]
|
|
102
|
+
fd = os.open("/", flags)
|
|
103
|
+
st = os.fstat(fd)
|
|
104
|
+
ids.append((st.st_dev, st.st_ino))
|
|
105
|
+
links = 0
|
|
106
|
+
tail: List[str] = []
|
|
107
|
+
last_name = ""
|
|
108
|
+
base_override = ""
|
|
109
|
+
complete = True
|
|
110
|
+
try:
|
|
111
|
+
while todo:
|
|
112
|
+
part = todo.pop(0)
|
|
113
|
+
if part == "..":
|
|
114
|
+
try:
|
|
115
|
+
nxt = os.open("..", flags, dir_fd=fd)
|
|
116
|
+
except OSError:
|
|
117
|
+
complete = False
|
|
118
|
+
break
|
|
119
|
+
os.close(fd)
|
|
120
|
+
fd = nxt
|
|
121
|
+
st = os.fstat(fd)
|
|
122
|
+
ids.append((st.st_dev, st.st_ino))
|
|
123
|
+
continue
|
|
124
|
+
try:
|
|
125
|
+
st = os.stat(part, dir_fd=fd, follow_symlinks=False)
|
|
126
|
+
except FileNotFoundError:
|
|
127
|
+
st = None
|
|
128
|
+
except OSError:
|
|
129
|
+
complete = False
|
|
130
|
+
break
|
|
131
|
+
if st is None:
|
|
132
|
+
# some folders resolve a name only by full path (macOS /.vol/<dev>/<inode>):
|
|
133
|
+
# try longer prefixes of the rest, as a folder, then as anything else
|
|
134
|
+
here = _from_fd(fd)
|
|
135
|
+
opened = -1
|
|
136
|
+
if here and (here == "/.vol" or here.startswith("/.vol/")):
|
|
137
|
+
for k in range(0, min(len(todo), 3) + 1):
|
|
138
|
+
if any(x == ".." for x in todo[:k]):
|
|
139
|
+
break
|
|
140
|
+
full = os.path.join(here, part, *todo[:k])
|
|
141
|
+
for fl in (flags, _file_flags()):
|
|
142
|
+
try:
|
|
143
|
+
opened = os.open(full, fl)
|
|
144
|
+
break
|
|
145
|
+
except OSError:
|
|
146
|
+
opened = -1
|
|
147
|
+
if opened >= 0:
|
|
148
|
+
del todo[:k]
|
|
149
|
+
break
|
|
150
|
+
if opened < 0:
|
|
151
|
+
complete = False # an inode name we cannot follow: fail closed
|
|
152
|
+
break
|
|
153
|
+
os.close(fd)
|
|
154
|
+
fd = opened
|
|
155
|
+
st = os.fstat(fd)
|
|
156
|
+
ids.append((st.st_dev, st.st_ino))
|
|
157
|
+
if not stat.S_ISDIR(st.st_mode):
|
|
158
|
+
base_override = _from_fd(fd) or ""
|
|
159
|
+
if not base_override:
|
|
160
|
+
complete = False
|
|
161
|
+
tail = todo
|
|
162
|
+
todo = []
|
|
163
|
+
break
|
|
164
|
+
continue
|
|
165
|
+
# the generic rule: a name the walk cannot find, but
|
|
166
|
+
# that the kernel resolves as part of the whole path (macOS /.nofollow,
|
|
167
|
+
# /.resolve/N, ...), is not a missing tail: fail closed
|
|
168
|
+
here = _from_fd(fd) or "/"
|
|
169
|
+
try:
|
|
170
|
+
os.lstat(os.path.join(here, part, *todo))
|
|
171
|
+
complete = False
|
|
172
|
+
break
|
|
173
|
+
except OSError:
|
|
174
|
+
pass
|
|
175
|
+
tail = [part] + todo
|
|
176
|
+
todo = []
|
|
177
|
+
break
|
|
178
|
+
if stat.S_ISLNK(st.st_mode):
|
|
179
|
+
links += 1
|
|
180
|
+
if links > MAX_LINKS:
|
|
181
|
+
complete = False # a loop: fail closed
|
|
182
|
+
break
|
|
183
|
+
target = os.readlink(part, dir_fd=fd)
|
|
184
|
+
if _on_procfs(fd):
|
|
185
|
+
kind = _proc_link_kind(_from_fd(fd) or "", part, target)
|
|
186
|
+
if kind == "magic":
|
|
187
|
+
# its text is not where it leads: let the kernel follow it, ask the
|
|
188
|
+
# kernel where it really is, and walk that; use the answer only if the
|
|
189
|
+
# identities agree, else fail closed
|
|
190
|
+
resolved = _follow_magic(fd, part, todo)
|
|
191
|
+
if resolved is None:
|
|
192
|
+
complete = False
|
|
193
|
+
break
|
|
194
|
+
os.close(fd)
|
|
195
|
+
fd = os.open("/", flags)
|
|
196
|
+
return resolved
|
|
197
|
+
if kind == "not-a-path": # pipe:, socket:, anon_inode:
|
|
198
|
+
last_name = part
|
|
199
|
+
tail = []
|
|
200
|
+
todo = []
|
|
201
|
+
break
|
|
202
|
+
more = [p for p in target.split("/") if p and p != "."]
|
|
203
|
+
if target.startswith("/"):
|
|
204
|
+
os.close(fd)
|
|
205
|
+
fd = os.open("/", flags)
|
|
206
|
+
todo = more + todo
|
|
207
|
+
continue
|
|
208
|
+
if stat.S_ISDIR(st.st_mode):
|
|
209
|
+
try:
|
|
210
|
+
nxt = os.open(part, flags | os.O_NOFOLLOW, dir_fd=fd)
|
|
211
|
+
except OSError:
|
|
212
|
+
complete = False
|
|
213
|
+
break
|
|
214
|
+
os.close(fd)
|
|
215
|
+
fd = nxt
|
|
216
|
+
st = os.fstat(fd)
|
|
217
|
+
ids.append((st.st_dev, st.st_ino))
|
|
218
|
+
continue
|
|
219
|
+
# a file, device, FIFO or socket: looked up only
|
|
220
|
+
ids.append((st.st_dev, st.st_ino))
|
|
221
|
+
last_name = part
|
|
222
|
+
tail = todo
|
|
223
|
+
todo = []
|
|
224
|
+
base = base_override or _from_fd(fd) or "/"
|
|
225
|
+
finally:
|
|
226
|
+
os.close(fd)
|
|
227
|
+
out: List[str] = []
|
|
228
|
+
for p in ([last_name] if last_name else []) + tail:
|
|
229
|
+
if p == "..":
|
|
230
|
+
if out:
|
|
231
|
+
out.pop()
|
|
232
|
+
elif p and p != ".":
|
|
233
|
+
out.append(p)
|
|
234
|
+
return Walk(os.path.join(base, *out) if out else base, ids, complete)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
_PROC_SUPER_MAGIC = 0x9FA0
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def _on_procfs(fd: int) -> bool:
|
|
241
|
+
"""Linux: whether the folder `fd` is on procfs, asked of the file system (fstatfs), not
|
|
242
|
+
guessed from its path (procfs can be mounted at a second path)."""
|
|
243
|
+
if not LINUX:
|
|
244
|
+
return False
|
|
245
|
+
import ctypes
|
|
246
|
+
import ctypes.util
|
|
247
|
+
|
|
248
|
+
class _StatFs(ctypes.Structure):
|
|
249
|
+
_fields_ = [("f_type", ctypes.c_long), ("_rest", ctypes.c_byte * 120)]
|
|
250
|
+
|
|
251
|
+
libc = ctypes.CDLL(ctypes.util.find_library("c") or None, use_errno=True)
|
|
252
|
+
buf = _StatFs()
|
|
253
|
+
if libc.fstatfs(fd, ctypes.byref(buf)) != 0:
|
|
254
|
+
return True # unknown: treat as procfs (fail closed on its links)
|
|
255
|
+
return (buf.f_type & 0xFFFFFFFF) == _PROC_SUPER_MAGIC
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def _follow_magic(fd: int, part: str, rest: List[str]) -> Optional["Walk"]:
|
|
259
|
+
"""A magic link of another process, followed by the kernel and checked by identity; None
|
|
260
|
+
(fail closed) for this process's own links: /proc/self in the hook is the hook, not the
|
|
261
|
+
agent tool whose path this is."""
|
|
262
|
+
if not LINUX:
|
|
263
|
+
return None
|
|
264
|
+
here = _from_fd(fd)
|
|
265
|
+
if not here:
|
|
266
|
+
return None
|
|
267
|
+
mine = {str(os.getpid()), str(getattr(os, "gettid", os.getpid)())}
|
|
268
|
+
if any(c in mine for c in here.split("/")):
|
|
269
|
+
return None
|
|
270
|
+
full = os.path.join(here, part, *rest)
|
|
271
|
+
try:
|
|
272
|
+
tfd = os.open(full, os.O_PATH | os.O_CLOEXEC) # type: ignore[attr-defined]
|
|
273
|
+
except OSError:
|
|
274
|
+
return None
|
|
275
|
+
try:
|
|
276
|
+
real = os.readlink(f"/proc/self/fd/{tfd}")
|
|
277
|
+
st = os.fstat(tfd)
|
|
278
|
+
except OSError:
|
|
279
|
+
return None
|
|
280
|
+
finally:
|
|
281
|
+
os.close(tfd)
|
|
282
|
+
if not real.startswith("/") or real.startswith("/proc/"):
|
|
283
|
+
return None
|
|
284
|
+
try:
|
|
285
|
+
w = walk_full(real)
|
|
286
|
+
except OSError:
|
|
287
|
+
return None
|
|
288
|
+
if w.complete and w.ids and w.ids[-1] == (st.st_dev, st.st_ino):
|
|
289
|
+
return w
|
|
290
|
+
return None
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
_MAGIC_NAMES = ("root", "cwd", "exe")
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def _proc_link_kind(folder: str, name: str, target: str) -> str:
|
|
297
|
+
"""'plain' (follow it as text: /proc/self, /proc/thread-self, /proc/mounts), 'not-a-path'
|
|
298
|
+
(an fd link to a pipe, socket or anon inode), or 'magic' (root, cwd, exe, fd/*, map_files/*,
|
|
299
|
+
also under task/*: their text is not where they lead)."""
|
|
300
|
+
if re_not_a_path(target):
|
|
301
|
+
return "not-a-path"
|
|
302
|
+
last = os.path.basename(folder)
|
|
303
|
+
if name in _MAGIC_NAMES or last in ("fd", "map_files"):
|
|
304
|
+
return "magic" # also a tty-named one: checked by identity
|
|
305
|
+
return "plain"
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def re_not_a_path(target: str) -> bool:
|
|
309
|
+
return any(target.startswith(p) for p in ("pipe:", "socket:", "anon_inode:", "net:", "mnt:"))
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
def walk(path: str) -> Tuple[str, List[Tuple[int, int]]]:
|
|
313
|
+
w = walk_full(path)
|
|
314
|
+
return w.canon, w.ids
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
def canon(path: str) -> str:
|
|
318
|
+
"""The canonical spelling of an absolute path (see `walk`). When the walk cannot finish,
|
|
319
|
+
the spelling it reached is a prefix of the path, not the path: use `realpath` then."""
|
|
320
|
+
try:
|
|
321
|
+
w = walk_full(path)
|
|
322
|
+
except (OSError, ValueError):
|
|
323
|
+
return os.path.realpath(path)
|
|
324
|
+
return w.canon if w.complete else os.path.realpath(path)
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def canon_new(path: str) -> str:
|
|
329
|
+
"""The canonical spelling of a path that may not exist yet: its nearest existing folder in
|
|
330
|
+
the file system's own spelling (macOS firmlinks such as /System/Volumes/Data undone), with
|
|
331
|
+
the rest of the path after it."""
|
|
332
|
+
head, rest = path, ""
|
|
333
|
+
while not os.path.exists(head):
|
|
334
|
+
up = os.path.dirname(head)
|
|
335
|
+
if up == head:
|
|
336
|
+
return path
|
|
337
|
+
rest = os.path.join(os.path.basename(head), rest) if rest else os.path.basename(head)
|
|
338
|
+
head = up
|
|
339
|
+
c = canon(head)
|
|
340
|
+
return os.path.join(c, rest) if rest else c
|
|
341
|
+
|
|
342
|
+
def spellings(path: str) -> List[str]:
|
|
343
|
+
"""The path as written (normalized), resolved, and canonical, without duplicates."""
|
|
344
|
+
out: List[str] = []
|
|
345
|
+
for v in (os.path.normpath(path), os.path.realpath(path), canon(path)):
|
|
346
|
+
if v not in out:
|
|
347
|
+
out.append(v)
|
|
348
|
+
return out
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def home(env=None) -> str:
|
|
352
|
+
"""The home folder: `HOME` of `env` (os.environ by default), else the account's. The one
|
|
353
|
+
lookup (selfcheck, a standalone child, keeps its own; the user config's base uses the real
|
|
354
|
+
home on purpose: config.user_config_path)."""
|
|
355
|
+
env = os.environ if env is None else env
|
|
356
|
+
return env.get("HOME") or os.path.expanduser("~")
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def identity(path: str) -> Optional[Tuple[int, int]]:
|
|
360
|
+
try:
|
|
361
|
+
st = os.stat(path)
|
|
362
|
+
except OSError:
|
|
363
|
+
return None
|
|
364
|
+
return st.st_dev, st.st_ino
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
def case_sensitive(path: str) -> bool:
|
|
368
|
+
"""Whether the volume that holds `path` tells letter case apart (macOS asks the volume;
|
|
369
|
+
Linux: yes, except in a casefold folder, see `casefold_folder`)."""
|
|
370
|
+
if MACOS:
|
|
371
|
+
here = path
|
|
372
|
+
while here and not os.path.exists(here):
|
|
373
|
+
here = os.path.dirname(here)
|
|
374
|
+
try:
|
|
375
|
+
return bool(os.pathconf(here or "/", 11)) # _PC_CASE_SENSITIVE
|
|
376
|
+
except (OSError, ValueError):
|
|
377
|
+
return False # unknown: fold (stricter for deny decisions)
|
|
378
|
+
return not casefold_folder(path)
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def casefold_folder(path: str) -> bool:
|
|
382
|
+
"""Linux: whether a folder on the way has the casefold attribute (ext4, f2fs)."""
|
|
383
|
+
if not LINUX:
|
|
384
|
+
return False
|
|
385
|
+
import fcntl
|
|
386
|
+
import struct
|
|
387
|
+
here = path
|
|
388
|
+
while here and here != "/":
|
|
389
|
+
try:
|
|
390
|
+
fd = os.open(here, os.O_RDONLY | os.O_DIRECTORY | os.O_NONBLOCK | os.O_CLOEXEC)
|
|
391
|
+
except OSError:
|
|
392
|
+
here = os.path.dirname(here)
|
|
393
|
+
continue
|
|
394
|
+
try:
|
|
395
|
+
buf = fcntl.ioctl(fd, 0x80086601, struct.pack("l", 0)) # FS_IOC_GETFLAGS
|
|
396
|
+
if struct.unpack("l", buf)[0] & 0x40000000: # FS_CASEFOLD_FL
|
|
397
|
+
return True
|
|
398
|
+
except OSError:
|
|
399
|
+
pass
|
|
400
|
+
finally:
|
|
401
|
+
os.close(fd)
|
|
402
|
+
here = os.path.dirname(here)
|
|
403
|
+
return False
|
phiward/pathmatch.py
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""One meaning for a protected pattern, used by every part.
|
|
2
|
+
|
|
3
|
+
A pattern is an absolute path whose parts may hold `*`: any run of characters inside one path
|
|
4
|
+
part (never `/`), matching a name that starts with a dot too. Nothing else is a wildcard: `?` and
|
|
5
|
+
`[...]` are refused, and so is any character outside printable ASCII (Seatbelt matches
|
|
6
|
+
case-folded NFD bytes, Python matches code points, and the two disagree on classes, `?` and
|
|
7
|
+
non-ASCII names). With only `*` and ASCII literals, every back-end agrees by construction.
|
|
8
|
+
On macOS, letter case is folded (its volumes ignore case by default).
|
|
9
|
+
|
|
10
|
+
- `problem(pattern)`: why a pattern cannot be used, with a suggested rewrite, or None;
|
|
11
|
+
- `match_path(pattern, path)`: whether `path` is a match (not below one);
|
|
12
|
+
- `matches(pattern)`: the paths on disk that match, dot-names included, never through a link;
|
|
13
|
+
- `regex(pattern)`: an anchored-at-start regular expression for the same set, in the syntax that
|
|
14
|
+
both Python `re` and Seatbelt accept.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
import os
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
from fnmatch import fnmatchcase
|
|
21
|
+
from typing import List, Optional
|
|
22
|
+
|
|
23
|
+
FOLD_CASE = sys.platform == "darwin"
|
|
24
|
+
WILD = re.compile(r"[*?\[]")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def fold(p: str) -> str:
|
|
28
|
+
return p.casefold() if FOLD_CASE else p
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def parts(path: str) -> List[str]:
|
|
32
|
+
return [c for c in path.split("/") if c]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def match_part(pattern_part: str, name: str) -> bool:
|
|
36
|
+
return fnmatchcase(fold(name), fold(pattern_part))
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def match_path(pattern: str, path: str) -> bool:
|
|
40
|
+
pp, xp = parts(pattern), parts(path)
|
|
41
|
+
return len(pp) == len(xp) and all(match_part(a, b) for a, b in zip(pp, xp))
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
_LITERAL = re.compile(r"[ -~]") # printable ASCII, space included
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def problem(pattern: str) -> Optional[str]:
|
|
48
|
+
"""Why a pattern cannot be used (with a suggested rewrite), or None."""
|
|
49
|
+
if any(p in ("", ".", "..") for p in pattern.split("/")[1:]):
|
|
50
|
+
# the matcher and the kernel would read such a part differently
|
|
51
|
+
return "a pattern may not hold empty, `.` or `..` parts; write the folder as it is"
|
|
52
|
+
for ch in pattern:
|
|
53
|
+
if ch in "?[]":
|
|
54
|
+
return ("only `*` is a wildcard (`?` and `[...]` are not accepted, so that every part "
|
|
55
|
+
"of phiward reads the pattern the same way); use `*` there, or list the "
|
|
56
|
+
"folders as roots")
|
|
57
|
+
if ch == "\\":
|
|
58
|
+
return "a backslash is not accepted in a pattern"
|
|
59
|
+
if not _LITERAL.fullmatch(ch):
|
|
60
|
+
return ("a pattern may hold only printable ASCII; give a folder with other characters "
|
|
61
|
+
"in its name as a root")
|
|
62
|
+
return None
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _part_regex(part: str) -> str:
|
|
66
|
+
return "".join("[^/]*" if ch == "*" else ("\\" + ch if ch in ".^$+(){}|\\" else ch)
|
|
67
|
+
for ch in part)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def regex(pattern: str) -> str:
|
|
71
|
+
"""`^` and the pattern, as a regex for whole paths (add your own end)."""
|
|
72
|
+
return "^/" + "/".join(_part_regex(p) for p in parts(pattern))
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def matches(pattern: str) -> List[str]:
|
|
76
|
+
"""Paths on disk that match, dot-names included. A folder on the way is entered only when it
|
|
77
|
+
is a real folder (not a link), so a match is never reached through a link the agent put
|
|
78
|
+
there. The literal leading part is taken as written."""
|
|
79
|
+
pp = parts(pattern)
|
|
80
|
+
out = ["/"]
|
|
81
|
+
for k, part in enumerate(pp):
|
|
82
|
+
nxt: List[str] = []
|
|
83
|
+
for base in out:
|
|
84
|
+
if not WILD.search(part):
|
|
85
|
+
cand = os.path.join(base, part)
|
|
86
|
+
if os.path.lexists(cand):
|
|
87
|
+
nxt.append(cand)
|
|
88
|
+
continue
|
|
89
|
+
try:
|
|
90
|
+
names = os.listdir(base)
|
|
91
|
+
except OSError:
|
|
92
|
+
continue
|
|
93
|
+
nxt += [os.path.join(base, n) for n in names if match_part(part, n)]
|
|
94
|
+
if k < len(pp) - 1: # enter only real folders, except along the literal prefix
|
|
95
|
+
literal = not any(WILD.search(p) for p in pp[:k + 1])
|
|
96
|
+
nxt = [p for p in nxt if os.path.isdir(p) and (literal or not os.path.islink(p))]
|
|
97
|
+
out = nxt
|
|
98
|
+
return sorted(out)
|