mareforma-pro 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.
@@ -0,0 +1,98 @@
1
+ """Rootless, no-sudo observation extension for Mareforma."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ from .backend import CollectorBackend, EvidenceBackend, InProcessBackend
6
+ from .collector import RootlessCollector
7
+ from .errors import (
8
+ FuseMountError,
9
+ MareformaProError,
10
+ ReceiptError,
11
+ RootlessRunError,
12
+ RootlessUnavailableError,
13
+ ScopeError,
14
+ )
15
+ from .evidence import ScopeEvidence, ScopeRegistration, VerifiedScopeEvidence
16
+ from .fuse import FuseReadOnlyProxy
17
+ from .jupyter import JupyterCellResult, JupyterScopeHook, audit_scope
18
+ from .mcp import (
19
+ MCPApplicationMiddleware,
20
+ MCPContext,
21
+ MCPObservation,
22
+ inject_meta,
23
+ payload_digest,
24
+ record_mcp_payload,
25
+ )
26
+ from .observe import (
27
+ ReceiptVerifier,
28
+ RootlessObservation,
29
+ assert_claim_from_receipt,
30
+ observe,
31
+ verdict_from_evidence,
32
+ verdict_or_opaque,
33
+ verify_and_verdict,
34
+ )
35
+ from .otel import (
36
+ AsyncJsonlSpanExporter,
37
+ OTLPSpanExporterAdapter,
38
+ process_spans_from_evidence,
39
+ scope_span_from_evidence,
40
+ )
41
+ from .paths import MountResolver
42
+ from .receipt import sign_receipt, verify_scope_receipt, verify_signature
43
+ from .runner import FuseRunResult, RootlessBwrapRunner, RootlessFuseRunner, RunResult
44
+ from .server import CollectorClient, CollectorServer
45
+ from .store import ReceiptStore
46
+ from .strace import TRACE_EXPR, ParsedStrace, StraceParser, parse_strace
47
+
48
+ __all__ = [
49
+ "AsyncJsonlSpanExporter",
50
+ "CollectorBackend",
51
+ "CollectorClient",
52
+ "CollectorServer",
53
+ "EvidenceBackend",
54
+ "FuseMountError",
55
+ "FuseReadOnlyProxy",
56
+ "FuseRunResult",
57
+ "InProcessBackend",
58
+ "JupyterCellResult",
59
+ "JupyterScopeHook",
60
+ "MCPApplicationMiddleware",
61
+ "MCPContext",
62
+ "MCPObservation",
63
+ "MareformaProError",
64
+ "MountResolver",
65
+ "OTLPSpanExporterAdapter",
66
+ "ParsedStrace",
67
+ "ReceiptError",
68
+ "ReceiptStore",
69
+ "RootlessBwrapRunner",
70
+ "RootlessCollector",
71
+ "RootlessFuseRunner",
72
+ "ReceiptVerifier",
73
+ "RootlessObservation",
74
+ "RootlessRunError",
75
+ "RootlessUnavailableError",
76
+ "RunResult",
77
+ "ScopeError",
78
+ "ScopeEvidence",
79
+ "ScopeRegistration",
80
+ "StraceParser",
81
+ "TRACE_EXPR",
82
+ "VerifiedScopeEvidence",
83
+ "assert_claim_from_receipt",
84
+ "audit_scope",
85
+ "inject_meta",
86
+ "observe",
87
+ "parse_strace",
88
+ "process_spans_from_evidence",
89
+ "payload_digest",
90
+ "record_mcp_payload",
91
+ "scope_span_from_evidence",
92
+ "sign_receipt",
93
+ "verdict_from_evidence",
94
+ "verdict_or_opaque",
95
+ "verify_and_verdict",
96
+ "verify_scope_receipt",
97
+ "verify_signature",
98
+ ]
@@ -0,0 +1,4 @@
1
+ from .cli import cli
2
+
3
+ if __name__ == "__main__":
4
+ cli()
@@ -0,0 +1,96 @@
1
+ """Backend abstraction for in-process and rootless evidence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from abc import ABC, abstractmethod
6
+ from typing import Any, Iterable, Mapping
7
+
8
+ from .collector import RootlessCollector
9
+ from .evidence import ScopeRegistration, VerifiedScopeEvidence
10
+
11
+
12
+ class EvidenceBackend(ABC):
13
+ """The small seam the core observer needs for external evidence."""
14
+
15
+ @abstractmethod
16
+ def open_scope(self, registration: ScopeRegistration) -> None:
17
+ """Open a scope before the observed command is released."""
18
+
19
+ @abstractmethod
20
+ def close_and_fetch(self, scope_id: str) -> VerifiedScopeEvidence:
21
+ """Close the scope, verify its receipt, and return evidence."""
22
+
23
+ def ingest_strace_path(self, scope_id: str, path: str) -> Any:
24
+ raise NotImplementedError
25
+
26
+ def ingest_events(
27
+ self,
28
+ scope_id: str,
29
+ *,
30
+ observed_files: Iterable[str] = (),
31
+ observed_dirs: Iterable[str] = (),
32
+ opened_only: Iterable[str] = (),
33
+ payload_digests: Iterable[str] = (),
34
+ opaque_reasons: Iterable[str] = (),
35
+ ) -> None:
36
+ raise NotImplementedError
37
+
38
+
39
+ class InProcessBackend(EvidenceBackend):
40
+ """Marker backend that preserves the original process-local observer."""
41
+
42
+ def open_scope(self, registration: ScopeRegistration) -> None:
43
+ raise RuntimeError("InProcessBackend is handled by mareforma_pro.observe")
44
+
45
+ def close_and_fetch(self, scope_id: str) -> VerifiedScopeEvidence:
46
+ raise RuntimeError("InProcessBackend is handled by mareforma_pro.observe")
47
+
48
+
49
+ class CollectorBackend(EvidenceBackend):
50
+ """Wrap a :class:`RootlessCollector` as an external evidence backend."""
51
+
52
+ def __init__(self, collector: RootlessCollector) -> None:
53
+ self.collector = collector
54
+
55
+ def open_scope(self, registration: ScopeRegistration) -> None:
56
+ self.collector.open_scope(
57
+ registration.scope_id,
58
+ mount_map=registration.mount_map,
59
+ tmpfs_mounts=registration.tmpfs_mounts,
60
+ root_passthrough=registration.root_passthrough,
61
+ traceparent=registration.traceparent,
62
+ parent_scope_id=registration.parent_scope_id,
63
+ evidence_level=registration.evidence_level,
64
+ read_semantics=registration.read_semantics,
65
+ collector_mode=registration.collector_mode,
66
+ coverage_roots=registration.coverage_roots,
67
+ )
68
+
69
+ def close_and_fetch(self, scope_id: str) -> VerifiedScopeEvidence:
70
+ evidence = self.collector.close_scope(scope_id)
71
+ return self.collector.verify(evidence)
72
+
73
+ def ingest_strace_path(self, scope_id: str, path: str) -> Any:
74
+ return self.collector.ingest_strace_path(scope_id, path)
75
+
76
+ def ingest_events(
77
+ self,
78
+ scope_id: str,
79
+ *,
80
+ observed_files: Iterable[str] = (),
81
+ observed_dirs: Iterable[str] = (),
82
+ opened_only: Iterable[str] = (),
83
+ payload_digests: Iterable[str] = (),
84
+ opaque_reasons: Iterable[str] = (),
85
+ ) -> None:
86
+ self.collector.ingest_events(
87
+ scope_id,
88
+ observed_files=observed_files,
89
+ observed_dirs=observed_dirs,
90
+ opened_only=opened_only,
91
+ payload_digests=payload_digests,
92
+ opaque_reasons=opaque_reasons,
93
+ )
94
+
95
+ def verify(self, receipt: Mapping[str, Any] | object) -> VerifiedScopeEvidence:
96
+ return self.collector.verify(receipt) # type: ignore[arg-type]
mareforma_pro/cli.py ADDED
@@ -0,0 +1,315 @@
1
+ """Command line interface for the rootless observation extension."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import shutil
9
+ import subprocess
10
+ import tempfile
11
+ from typing import Iterable
12
+
13
+ import click
14
+
15
+ from .collector import RootlessCollector
16
+ from .errors import MareformaProError
17
+ from .observe import verify_and_verdict
18
+ from .otel import AsyncJsonlSpanExporter
19
+ from .runner import RootlessBwrapRunner, RootlessFuseRunner
20
+ from .server import CollectorServer
21
+ from .store import ReceiptStore
22
+
23
+
24
+ def _secret(value: str | None) -> str:
25
+ secret = value or os.environ.get("MAREFORMA_HMAC_SECRET", "")
26
+ if not secret:
27
+ raise click.ClickException("set --secret or MAREFORMA_HMAC_SECRET")
28
+ return secret
29
+
30
+
31
+ def _bind_pairs(values: Iterable[str]) -> dict[str, str]:
32
+ out: dict[str, str] = {}
33
+ for value in values:
34
+ if ":" not in value:
35
+ raise click.BadParameter(f"expected HOST:SANDBOX, got {value!r}")
36
+ host, sandbox = value.split(":", 1)
37
+ if not host or not sandbox:
38
+ raise click.BadParameter(f"expected HOST:SANDBOX, got {value!r}")
39
+ out[host] = sandbox
40
+ return out
41
+
42
+
43
+ @click.group()
44
+ def cli() -> None:
45
+ """Rootless, no-sudo observation helpers for Mareforma."""
46
+
47
+
48
+ @cli.command()
49
+ @click.option("--json", "as_json", is_flag=True)
50
+ def doctor(as_json: bool) -> None:
51
+ """Report whether the no-sudo primitives are usable on this host."""
52
+ checks: list[dict[str, object]] = []
53
+
54
+ def add(name: str, ok: bool, detail: str, *, required: bool = True) -> None:
55
+ checks.append({"name": name, "ok": ok, "detail": detail, "required": required})
56
+
57
+ strace = shutil.which("strace")
58
+ bwrap = shutil.which("bwrap")
59
+ fusermount = shutil.which("fusermount3") or shutil.which("fusermount")
60
+ ptrace_scope = None
61
+ try:
62
+ ptrace_scope = Path("/proc/sys/kernel/yama/ptrace_scope").read_text().strip()
63
+ except OSError:
64
+ pass
65
+ add("strace", bool(strace), strace or "not installed")
66
+ add("bwrap", bool(bwrap), bwrap or "not installed")
67
+ # These describe the optional P2 FUSE route and host policy. A missing
68
+ # /dev/fuse must not fail a P1 host: the default path never uses it.
69
+ add(
70
+ "ptrace_scope",
71
+ ptrace_scope in (None, "0", "1", "2"),
72
+ ptrace_scope or "not exposed",
73
+ required=False,
74
+ )
75
+ add("fuse_device", Path("/dev/fuse").exists(), str(Path("/dev/fuse")), required=False)
76
+ add("fusermount3", bool(fusermount), fusermount or "not installed", required=False)
77
+ if strace:
78
+ try:
79
+ probe = subprocess.run(
80
+ [strace, "--seccomp-bpf", "-qq", "-f", "-e", "trace=none", "--", "/bin/true"],
81
+ capture_output=True,
82
+ text=True,
83
+ timeout=3,
84
+ check=False,
85
+ )
86
+ detail = (probe.stderr or probe.stdout or "no output").strip()[:160]
87
+ add("seccomp_bpf", probe.returncode == 0, detail)
88
+ except (OSError, subprocess.TimeoutExpired) as exc:
89
+ add("seccomp_bpf", False, str(exc))
90
+ report = {
91
+ "ok": all(bool(c["ok"]) for c in checks if c["required"]),
92
+ "checks": checks,
93
+ }
94
+ if as_json:
95
+ click.echo(json.dumps(report, indent=2, sort_keys=True))
96
+ else:
97
+ for check in checks:
98
+ label = "OK" if check["ok"] else ("WARN" if check["required"] else "OPTIONAL")
99
+ click.echo(f"[{label}] {check['name']}: {check['detail']}")
100
+ if not report["ok"]:
101
+ raise click.exceptions.Exit(1)
102
+
103
+
104
+ @cli.command(context_settings={"ignore_unknown_options": True, "allow_extra_args": True})
105
+ @click.argument("command", nargs=-1, type=click.UNPROCESSED, required=True)
106
+ @click.option("--secret", default=None, help="HMAC secret; prefer MAREFORMA_HMAC_SECRET.")
107
+ @click.option("--cite", "cites", multiple=True, help="Cited source path/URL.")
108
+ @click.option("--ro-bind", "ro_binds", multiple=True, help="HOST:SANDBOX read-only bind.")
109
+ @click.option("--rw-bind", "rw_binds", multiple=True, help="HOST:SANDBOX read-write bind.")
110
+ @click.option("--tmpfs", "tmpfs_mounts", multiple=True, default=("/tmp",), show_default=True)
111
+ @click.option("--timeout", default=60.0, show_default=True, type=float)
112
+ @click.option("--keep-log", is_flag=True)
113
+ @click.option("--json", "as_json", is_flag=True)
114
+ def run(
115
+ command: tuple[str, ...],
116
+ secret: str | None,
117
+ cites: tuple[str, ...],
118
+ ro_binds: tuple[str, ...],
119
+ rw_binds: tuple[str, ...],
120
+ tmpfs_mounts: tuple[str, ...],
121
+ timeout: float,
122
+ keep_log: bool,
123
+ as_json: bool,
124
+ ) -> None:
125
+ """Run a command under bwrap+strace and emit a rootless receipt."""
126
+ if not command:
127
+ raise click.UsageError("a command is required after --")
128
+ try:
129
+ secret_value = _secret(secret)
130
+ collector = RootlessCollector(secret_value)
131
+ runner = RootlessBwrapRunner(collector)
132
+ result = runner.run_in_bwrap(
133
+ command,
134
+ ro_binds=_bind_pairs(ro_binds),
135
+ rw_binds=_bind_pairs(rw_binds),
136
+ tmpfs_mounts=tmpfs_mounts,
137
+ timeout_sec=timeout,
138
+ keep_log=keep_log,
139
+ )
140
+ verdict = verify_and_verdict(
141
+ result.evidence.to_receipt_dict(),
142
+ secret=secret_value,
143
+ cites=cites,
144
+ )
145
+ except (MareformaProError, OSError, ValueError) as exc:
146
+ raise click.ClickException(str(exc)) from exc
147
+ payload = {
148
+ "returncode": result.process.returncode,
149
+ "receipt": result.evidence.to_receipt_dict(),
150
+ "grounding": verdict.to_signed_dict(),
151
+ }
152
+ if as_json:
153
+ click.echo(json.dumps(payload, indent=2, sort_keys=True))
154
+ else:
155
+ click.echo(f"returncode: {result.process.returncode}")
156
+ click.echo(f"grounding: {verdict.grounding.value}")
157
+ click.echo(f"observed_files: {list(result.evidence.observed_files)}")
158
+ click.echo(f"opened_only: {list(result.evidence.opened_only)}")
159
+ click.echo(f"opaque_reasons: {list(verdict.opaque_reasons)}")
160
+
161
+
162
+ @cli.command(name="run-fuse", context_settings={"ignore_unknown_options": True, "allow_extra_args": True})
163
+ @click.argument("command", nargs=-1, type=click.UNPROCESSED, required=True)
164
+ @click.option("--secret", default=None, help="HMAC secret; prefer MAREFORMA_HMAC_SECRET.")
165
+ @click.option(
166
+ "--source",
167
+ "source_root",
168
+ required=True,
169
+ type=click.Path(exists=True, file_okay=False, path_type=str),
170
+ help="Host directory exposed through the read-only FUSE view.",
171
+ )
172
+ @click.option(
173
+ "--sandbox-path",
174
+ default="/tmp/mareforma-data",
175
+ show_default=True,
176
+ help="Where the FUSE view is mounted inside bwrap.",
177
+ )
178
+ @click.option(
179
+ "--keep-source-visible",
180
+ is_flag=True,
181
+ help="Do not hide the original host source path inside bwrap (debug only).",
182
+ )
183
+ @click.option("--cite", "cites", multiple=True, help="Cited host source path/URL.")
184
+ @click.option("--tmpfs", "tmpfs_mounts", multiple=True, default=("/tmp",), show_default=True)
185
+ @click.option("--timeout", default=60.0, show_default=True, type=float)
186
+ @click.option("--json", "as_json", is_flag=True)
187
+ def run_fuse(
188
+ command: tuple[str, ...],
189
+ secret: str | None,
190
+ source_root: str,
191
+ sandbox_path: str,
192
+ keep_source_visible: bool,
193
+ cites: tuple[str, ...],
194
+ tmpfs_mounts: tuple[str, ...],
195
+ timeout: float,
196
+ as_json: bool,
197
+ ) -> None:
198
+ """Run a command under a rootless read-only FUSE view (no ptrace)."""
199
+ if not command:
200
+ raise click.UsageError("a command is required after --")
201
+ try:
202
+ secret_value = _secret(secret)
203
+ collector = RootlessCollector(secret_value)
204
+ runner = RootlessFuseRunner(collector)
205
+ result = runner.run_in_bwrap(
206
+ command,
207
+ source_root=source_root,
208
+ sandbox_path=sandbox_path,
209
+ hide_source_root=not keep_source_visible,
210
+ tmpfs_mounts=tmpfs_mounts,
211
+ timeout_sec=timeout,
212
+ )
213
+ verdict = verify_and_verdict(
214
+ result.evidence.to_receipt_dict(),
215
+ secret=secret_value,
216
+ cites=cites,
217
+ )
218
+ except (MareformaProError, OSError, ValueError) as exc:
219
+ raise click.ClickException(str(exc)) from exc
220
+ payload = {
221
+ "returncode": result.process.returncode,
222
+ "receipt": result.evidence.to_receipt_dict(),
223
+ "grounding": verdict.to_signed_dict(),
224
+ }
225
+ if as_json:
226
+ click.echo(json.dumps(payload, indent=2, sort_keys=True))
227
+ else:
228
+ click.echo(f"returncode: {result.process.returncode}")
229
+ click.echo(f"collector_mode: {result.evidence.collector_mode}")
230
+ click.echo(f"grounding: {verdict.grounding.value}")
231
+ click.echo(f"observed_files: {list(result.evidence.observed_files)}")
232
+ click.echo(f"opened_only: {list(result.evidence.opened_only)}")
233
+ click.echo(f"opaque_reasons: {list(verdict.opaque_reasons)}")
234
+
235
+
236
+ @cli.command()
237
+ @click.option("--socket", "socket_path", default="/tmp/mareforma-collector.sock", show_default=True)
238
+ @click.option("--secret", default=None)
239
+ @click.option("--token", default=None, help="Optional client token for the local socket.")
240
+ @click.option("--db", "db_path", default=None, help="SQLite receipt store.")
241
+ @click.option(
242
+ "--otel-jsonl",
243
+ "otel_jsonl",
244
+ default=None,
245
+ help="Write non-authoritative scope/process spans as JSONL.",
246
+ )
247
+ @click.option("--collector-id", default="rootless", show_default=True)
248
+ def serve(
249
+ socket_path: str,
250
+ secret: str | None,
251
+ token: str | None,
252
+ db_path: str | None,
253
+ otel_jsonl: str | None,
254
+ collector_id: str,
255
+ ) -> None:
256
+ """Serve the local rootless collector over a Unix socket."""
257
+ store = ReceiptStore(db_path) if db_path else None
258
+ secret_value = _secret(secret)
259
+ span_exporter = AsyncJsonlSpanExporter(otel_jsonl) if otel_jsonl else None
260
+ collector = RootlessCollector(
261
+ secret_value,
262
+ collector_id=collector_id,
263
+ store=store,
264
+ span_exporter=span_exporter,
265
+ )
266
+ server = CollectorServer(socket_path, collector, auth_token=token)
267
+ click.echo(f"mareforma-collector listening on {socket_path}")
268
+ try:
269
+ server.serve_in_thread()
270
+ while True:
271
+ import time
272
+
273
+ time.sleep(3600)
274
+ except KeyboardInterrupt:
275
+ pass
276
+ finally:
277
+ server.shutdown()
278
+ if span_exporter is not None:
279
+ span_exporter.close()
280
+ if store is not None:
281
+ store.close()
282
+
283
+
284
+ @cli.command()
285
+ @click.option("--secret", default=None)
286
+ def demo(secret: str | None) -> None:
287
+ """Run the four local sanity checks without a privileged host."""
288
+ secret_value = _secret(secret)
289
+ with tempfile.TemporaryDirectory(prefix="mareforma-pro-demo-") as tmp:
290
+ root = Path(tmp)
291
+ data = root / "results.csv"
292
+ data.write_text("metric,value\naccuracy,0.942\n", encoding="utf-8")
293
+ collector = RootlessCollector(secret_value)
294
+ runner = RootlessBwrapRunner(collector)
295
+ result = runner.run_in_bwrap(
296
+ ["/bin/sh", "-c", "cd /tmp/work && /bin/cat results.csv >/dev/null"],
297
+ ro_binds={str(root): "/tmp/work"},
298
+ )
299
+ verdict = verify_and_verdict(
300
+ result.evidence.to_receipt_dict(), secret=secret_value, cites=[str(data)]
301
+ )
302
+ click.echo(f"read verdict: {verdict.grounding.value}")
303
+ write_only = runner.run_in_bwrap(
304
+ ["/bin/sh", "-c", "echo 1 > /tmp/work/out.csv"],
305
+ rw_binds={str(root): "/tmp/work"},
306
+ )
307
+ verdict2 = verify_and_verdict(
308
+ write_only.evidence.to_receipt_dict(), secret=secret_value, cites=[str(root / "out.csv")]
309
+ )
310
+ click.echo(f"write-only verdict: {verdict2.grounding.value}")
311
+ click.echo(f"opaque reasons: {list(verdict2.opaque_reasons)}")
312
+
313
+
314
+ if __name__ == "__main__":
315
+ cli()