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/pin.py
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
"""`phiward pin`: approve the listed programs, and record the derived protected folders, as the
|
|
2
|
+
operator sees them now.
|
|
3
|
+
|
|
4
|
+
Derived roots (the git folders around a root, snapshot folders, other mounts of the same data)
|
|
5
|
+
are worked out from paths the agent may be able to write: a `.git` file planted closer to a root
|
|
6
|
+
would otherwise make the real git folder stop being protected on the next load. `pin` writes the
|
|
7
|
+
derived roots found from the operator's view to `pinned.toml` next to the user config (a guard
|
|
8
|
+
file: the agent cannot write it). Every later load uses the pinned folders and the folders it
|
|
9
|
+
finds, so a planted file can add protection but never remove a pinned folder. `doctor` warns
|
|
10
|
+
when the two differ.
|
|
11
|
+
|
|
12
|
+
It also approves the programs of `[broker] commands`: it lists each one with its path and a mark
|
|
13
|
+
(new, changed, not installed, a link that never runs, cannot be read), and after a yes records
|
|
14
|
+
the content of each. The broker runs only programs whose content is approved, and refuses every
|
|
15
|
+
request while one differs.
|
|
16
|
+
|
|
17
|
+
It runs only on a terminal (the operator's), shows the list, and writes after a yes. `setup`
|
|
18
|
+
pins after it writes the config.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
import os
|
|
22
|
+
import sys
|
|
23
|
+
from typing import List, Optional, Sequence, TextIO
|
|
24
|
+
|
|
25
|
+
from phiward import config
|
|
26
|
+
|
|
27
|
+
USAGE = ("Approve the programs of [broker] commands as they are now (the broker runs only "
|
|
28
|
+
"approved ones),\nand pin the folders phiward found that hold copies of protected data; "
|
|
29
|
+
"then restart the broker.\nRun it in your own terminal after you change a listed "
|
|
30
|
+
"program or add a script to your scripts folder.\nusage: phiward pin\n")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def pins_path(env: Optional[dict] = None) -> str:
|
|
34
|
+
return os.path.join(os.path.dirname(config.user_config_path(env)), "pinned.toml")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def pinnable(cfg: config.Config) -> List[str]:
|
|
38
|
+
"""The derived roots worth pinning: all but the cache folder (always derived)."""
|
|
39
|
+
return [d for d in (cfg.found_derived or cfg.derived_roots) if d != cfg.cache_dir]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def read_pins(env: Optional[dict] = None) -> List[str]:
|
|
43
|
+
from phiward import _toml
|
|
44
|
+
path = pins_path(env)
|
|
45
|
+
if not os.path.isfile(path):
|
|
46
|
+
return []
|
|
47
|
+
try:
|
|
48
|
+
raw, _ = _toml.load_file(path)
|
|
49
|
+
except Exception: # noqa: BLE001 - a bad file pins nothing; doctor reports it
|
|
50
|
+
return []
|
|
51
|
+
v = raw.get("pinned", {}).get("derived", []) if isinstance(raw, dict) else []
|
|
52
|
+
return [x for x in v if isinstance(x, str) and x.startswith("/")]
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def program_record(cfg: config.Config, path: Optional[str] = None) -> List[str]:
|
|
56
|
+
"""The programs `[broker] commands` allows, as the broker finds them now, each as
|
|
57
|
+
"sha256 path" (content, not just the name): what the operator approves with `pin`. `path`:
|
|
58
|
+
the PATH to find bare names on (the broker passes its own); else the running broker's."""
|
|
59
|
+
import hashlib
|
|
60
|
+
from phiward import broker
|
|
61
|
+
out: List[str] = []
|
|
62
|
+
for prog in broker.listed_programs(cfg, broker.program_path() if path is None else path):
|
|
63
|
+
if prog.startswith(("too-many:", "missing:", "linked:")):
|
|
64
|
+
out.append(f"{prog.split(':', 1)[0]} {prog.split(':', 1)[1]}")
|
|
65
|
+
continue
|
|
66
|
+
try:
|
|
67
|
+
with open(prog, "rb") as fh:
|
|
68
|
+
h = hashlib.sha256()
|
|
69
|
+
for chunk in iter(lambda: fh.read(1 << 20), b""):
|
|
70
|
+
h.update(chunk)
|
|
71
|
+
out.append(f"{h.hexdigest()} {prog}")
|
|
72
|
+
except OSError:
|
|
73
|
+
# there but not readable (mode 0111): its content cannot be approved, so it never
|
|
74
|
+
# is (a "missing" line would equal itself whatever the file holds)
|
|
75
|
+
out.append(f"{'unreadable' if os.path.lexists(prog) else 'missing'} {prog}")
|
|
76
|
+
return sorted(set(out))
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def read_approved(env: Optional[dict] = None) -> List[str]:
|
|
80
|
+
from phiward import _toml
|
|
81
|
+
try:
|
|
82
|
+
raw, _ = _toml.load_file(pins_path(env))
|
|
83
|
+
except Exception: # noqa: BLE001 - nothing approved
|
|
84
|
+
return []
|
|
85
|
+
v = raw.get("programs", {}).get("approved", []) if isinstance(raw, dict) else []
|
|
86
|
+
return [x for x in v if isinstance(x, str)]
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def unapproved(cfg: config.Config, env: Optional[dict] = None,
|
|
90
|
+
path: Optional[str] = None) -> List[str]:
|
|
91
|
+
"""The listed programs that differ from what the operator approved (empty without a list).
|
|
92
|
+
A program too large to check, or one that cannot be read, is never approved."""
|
|
93
|
+
if not cfg.command_lists:
|
|
94
|
+
return []
|
|
95
|
+
have = set(read_approved(env))
|
|
96
|
+
return [r.split(" ", 1)[1] for r in program_record(cfg, path)
|
|
97
|
+
if r not in have or r.startswith(("too-many ", "unreadable ", "linked "))]
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def describe(cfg: config.Config, env: Optional[dict] = None) -> List[str]:
|
|
101
|
+
"""The listed programs as `pin` and `doctor` show them: each marked (new), (changed),
|
|
102
|
+
(not installed) or (folder too large to check)."""
|
|
103
|
+
have = read_approved(env)
|
|
104
|
+
by_path = {r.split(" ", 1)[1]: r for r in have}
|
|
105
|
+
out = []
|
|
106
|
+
for r in program_record(cfg):
|
|
107
|
+
kind, path = r.split(" ", 1)
|
|
108
|
+
if kind == "too-many":
|
|
109
|
+
mark = " (folder too large to check: list fewer files)"
|
|
110
|
+
elif kind == "missing":
|
|
111
|
+
mark = " (not installed)"
|
|
112
|
+
elif kind == "linked":
|
|
113
|
+
mark = " (a link: never runs; list it by its name, or list its folder)"
|
|
114
|
+
elif kind == "unreadable":
|
|
115
|
+
mark = " (cannot be read: never approved)"
|
|
116
|
+
elif r in have:
|
|
117
|
+
mark = ""
|
|
118
|
+
elif path in by_path:
|
|
119
|
+
mark = " (changed)"
|
|
120
|
+
else:
|
|
121
|
+
mark = " (new)"
|
|
122
|
+
out.append(_shown_path(path) + mark)
|
|
123
|
+
return out
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def _shown_path(path: str) -> str:
|
|
127
|
+
"""A path as `pin`, `setup` and `doctor` print it: control characters written as `\\xNN`, so
|
|
128
|
+
a file name cannot steer the terminal or look like another path."""
|
|
129
|
+
import re
|
|
130
|
+
return re.sub(r"[\x00-\x1f\x7f-\x9f]", lambda m: "\\x%02x" % ord(m.group()), path)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def pins_readable(env: Optional[dict] = None) -> bool:
|
|
134
|
+
from phiward import _toml
|
|
135
|
+
try:
|
|
136
|
+
_toml.load_file(pins_path(env))
|
|
137
|
+
return True
|
|
138
|
+
except Exception: # noqa: BLE001
|
|
139
|
+
return False
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def write_pins(cfg: config.Config, env: Optional[dict] = None, add: Sequence[str] = (),
|
|
143
|
+
drop: Sequence[str] = (), approve: bool = True) -> int:
|
|
144
|
+
"""Pin what is found now, keep what was pinned, plus `add`, minus `drop`."""
|
|
145
|
+
from phiward.setup_cmd import _value
|
|
146
|
+
path = pins_path(env)
|
|
147
|
+
items = sorted((set(pinnable(cfg)) | set(read_pins(env)) | set(add)) - set(drop))
|
|
148
|
+
text = ("# Derived protected folders pinned by `phiward pin` (the agent cannot write\n"
|
|
149
|
+
"# this file). Every load protects these, as well as what it finds itself.\n\n"
|
|
150
|
+
f"[pinned]\nderived = {_value(items)}\n")
|
|
151
|
+
# the listed programs as they are now, or (approve=False) the approvals made before
|
|
152
|
+
progs = program_record(cfg) if approve else read_approved(env)
|
|
153
|
+
if progs:
|
|
154
|
+
text += ("\n# The programs [broker] commands allows, as approved: the broker runs no "
|
|
155
|
+
"listed\n# program whose content differs.\n"
|
|
156
|
+
f"[programs]\napproved = {_value(progs)}\n")
|
|
157
|
+
os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
|
|
158
|
+
from phiward import safeio
|
|
159
|
+
safeio.write_new(path, text)
|
|
160
|
+
return 0
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def main(argv: List[str], fin: Optional[TextIO] = None, fout: Optional[TextIO] = None) -> int:
|
|
164
|
+
fin = sys.stdin if fin is None else fin
|
|
165
|
+
fout = sys.stdout if fout is None else fout
|
|
166
|
+
if argv[:1] in (["-h"], ["--help"]):
|
|
167
|
+
fout.write(USAGE + "\n" + (__doc__ or ""))
|
|
168
|
+
return 0
|
|
169
|
+
if argv:
|
|
170
|
+
sys.stderr.write(USAGE)
|
|
171
|
+
return 2
|
|
172
|
+
try:
|
|
173
|
+
tty = fin.isatty() and fout.isatty()
|
|
174
|
+
except (AttributeError, ValueError):
|
|
175
|
+
tty = False
|
|
176
|
+
if not tty:
|
|
177
|
+
sys.stderr.write("phiward pin asks for a yes: run it in your own terminal, not "
|
|
178
|
+
"through an agent tool. Nothing was written.\n")
|
|
179
|
+
return 2
|
|
180
|
+
cfg = config.load(os.getcwd())
|
|
181
|
+
if cfg.problem:
|
|
182
|
+
fout.write(f"pin refused: the config cannot be used: {cfg.problem}\n")
|
|
183
|
+
return 3
|
|
184
|
+
found = set(pinnable(cfg))
|
|
185
|
+
items = sorted(found | set(read_pins()))
|
|
186
|
+
fout.write(f"Derived protected folders to pin ({len(items)}):\n")
|
|
187
|
+
for k, d in enumerate(items, 1):
|
|
188
|
+
mark = "" if d in found else " (pinned before, not found now)"
|
|
189
|
+
fout.write(f" {k}. {d}{mark}\n")
|
|
190
|
+
fout.write("Numbers to drop (for example 2 5), or an empty line to keep all: ")
|
|
191
|
+
fout.flush()
|
|
192
|
+
drop: List[str] = []
|
|
193
|
+
for w in fin.readline().split():
|
|
194
|
+
if w.isdigit() and 1 <= int(w) <= len(items):
|
|
195
|
+
drop.append(items[int(w) - 1])
|
|
196
|
+
progs = program_record(cfg)
|
|
197
|
+
if progs:
|
|
198
|
+
lines = describe(cfg)
|
|
199
|
+
missing = sum(1 for x in lines if x.endswith("(not installed)"))
|
|
200
|
+
fout.write("Programs of [broker] commands to approve as they are now "
|
|
201
|
+
f"({len(lines) - missing} found, {missing} not installed here):\n")
|
|
202
|
+
for line in lines:
|
|
203
|
+
if not line.endswith("(not installed)"):
|
|
204
|
+
fout.write(f" {line}\n")
|
|
205
|
+
fout.write(f"Write {len(items) - len(drop)} pin(s)" + (" and the programs" if progs else "")
|
|
206
|
+
+ f" to {pins_path()}? [y/N] ")
|
|
207
|
+
fout.flush()
|
|
208
|
+
if fin.readline().strip().lower() not in ("y", "yes"):
|
|
209
|
+
fout.write("Nothing was written.\n")
|
|
210
|
+
return 1
|
|
211
|
+
write_pins(cfg, drop=drop)
|
|
212
|
+
from phiward import broker
|
|
213
|
+
fout.write(f"Pinned. Restart the broker so it uses them: {broker.restart_hint()}.\n")
|
|
214
|
+
return 0
|
phiward/procinfo.py
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""A process's parent and start time, without starting a program: Linux reads `/proc/<pid>/stat`,
|
|
2
|
+
macOS asks the kernel (`proc_pidinfo`, the call `ps` makes). The start time tells a live process
|
|
3
|
+
from a later one that got the same number. None when it cannot tell: callers then trust
|
|
4
|
+
nothing."""
|
|
5
|
+
|
|
6
|
+
import os
|
|
7
|
+
import sys
|
|
8
|
+
from typing import List, Optional, Tuple
|
|
9
|
+
|
|
10
|
+
# (parent pid, start time in the system's own unit)
|
|
11
|
+
Info = Tuple[int, int]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _linux(pid: int) -> Optional[Info]:
|
|
15
|
+
try:
|
|
16
|
+
with open(f"/proc/{pid}/stat", "rb") as fh:
|
|
17
|
+
data = fh.read().decode("ascii", "replace")
|
|
18
|
+
except OSError:
|
|
19
|
+
return None
|
|
20
|
+
# the name (field 2) may hold spaces and parentheses: the fields after it follow the last ')'
|
|
21
|
+
rest = data[data.rfind(")") + 2:].split()
|
|
22
|
+
try:
|
|
23
|
+
return int(rest[1]), int(rest[19]) # field 4 ppid, field 22 starttime
|
|
24
|
+
except (IndexError, ValueError):
|
|
25
|
+
return None
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
_PROC_PIDTBSDINFO = 3
|
|
29
|
+
_BSDINFO_SIZE = 136 # struct proc_bsdinfo
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _darwin(pid: int) -> Optional[Info]:
|
|
33
|
+
import ctypes
|
|
34
|
+
import struct
|
|
35
|
+
try:
|
|
36
|
+
lib = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
|
|
37
|
+
except OSError:
|
|
38
|
+
return None
|
|
39
|
+
buf = ctypes.create_string_buffer(_BSDINFO_SIZE)
|
|
40
|
+
n = lib.proc_pidinfo(ctypes.c_int(pid), ctypes.c_int(_PROC_PIDTBSDINFO), ctypes.c_uint64(0),
|
|
41
|
+
buf, ctypes.c_int(_BSDINFO_SIZE))
|
|
42
|
+
if n != _BSDINFO_SIZE:
|
|
43
|
+
return None
|
|
44
|
+
got_pid, ppid = struct.unpack_from("=II", buf.raw, 12)
|
|
45
|
+
sec, usec = struct.unpack_from("=QQ", buf.raw, 120)
|
|
46
|
+
if got_pid != pid:
|
|
47
|
+
return None
|
|
48
|
+
return int(ppid), int(sec) * 1_000_000 + int(usec)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def info(pid: int) -> Optional[Info]:
|
|
52
|
+
"""(parent pid, start time) of a live process, or None."""
|
|
53
|
+
if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
|
|
54
|
+
return None
|
|
55
|
+
if sys.platform.startswith("linux"):
|
|
56
|
+
return _linux(pid)
|
|
57
|
+
if sys.platform == "darwin":
|
|
58
|
+
return _darwin(pid)
|
|
59
|
+
return None
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def ancestors(pid: Optional[int] = None, depth: int = 4) -> List[int]:
|
|
63
|
+
"""The parent, grandparent, ... of `pid` (this process by default), nearest first, at most
|
|
64
|
+
`depth`, never pid 1 (every orphan's parent) or 0."""
|
|
65
|
+
out: List[int] = []
|
|
66
|
+
cur = os.getpid() if pid is None else pid
|
|
67
|
+
for _ in range(depth):
|
|
68
|
+
got = info(cur)
|
|
69
|
+
if got is None or got[0] <= 1:
|
|
70
|
+
break
|
|
71
|
+
cur = got[0]
|
|
72
|
+
out.append(cur)
|
|
73
|
+
return out
|