mareforma-pro 0.1.0__tar.gz

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.
Files changed (40) hide show
  1. mareforma_pro-0.1.0/LICENSE +21 -0
  2. mareforma_pro-0.1.0/MANIFEST.in +5 -0
  3. mareforma_pro-0.1.0/PKG-INFO +100 -0
  4. mareforma_pro-0.1.0/README.md +68 -0
  5. mareforma_pro-0.1.0/pyproject.toml +69 -0
  6. mareforma_pro-0.1.0/setup.cfg +4 -0
  7. mareforma_pro-0.1.0/src/mareforma_pro/__init__.py +98 -0
  8. mareforma_pro-0.1.0/src/mareforma_pro/__main__.py +4 -0
  9. mareforma_pro-0.1.0/src/mareforma_pro/backend.py +96 -0
  10. mareforma_pro-0.1.0/src/mareforma_pro/cli.py +315 -0
  11. mareforma_pro-0.1.0/src/mareforma_pro/collector.py +261 -0
  12. mareforma_pro-0.1.0/src/mareforma_pro/errors.py +31 -0
  13. mareforma_pro-0.1.0/src/mareforma_pro/evidence.py +243 -0
  14. mareforma_pro-0.1.0/src/mareforma_pro/fuse.py +903 -0
  15. mareforma_pro-0.1.0/src/mareforma_pro/jupyter.py +182 -0
  16. mareforma_pro-0.1.0/src/mareforma_pro/mcp.py +159 -0
  17. mareforma_pro-0.1.0/src/mareforma_pro/observe.py +443 -0
  18. mareforma_pro-0.1.0/src/mareforma_pro/otel.py +221 -0
  19. mareforma_pro-0.1.0/src/mareforma_pro/paths.py +106 -0
  20. mareforma_pro-0.1.0/src/mareforma_pro/py.typed +0 -0
  21. mareforma_pro-0.1.0/src/mareforma_pro/receipt.py +96 -0
  22. mareforma_pro-0.1.0/src/mareforma_pro/runner.py +376 -0
  23. mareforma_pro-0.1.0/src/mareforma_pro/server.py +244 -0
  24. mareforma_pro-0.1.0/src/mareforma_pro/store.py +53 -0
  25. mareforma_pro-0.1.0/src/mareforma_pro/strace.py +332 -0
  26. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/PKG-INFO +100 -0
  27. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/SOURCES.txt +38 -0
  28. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/dependency_links.txt +1 -0
  29. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/entry_points.txt +2 -0
  30. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/requires.txt +12 -0
  31. mareforma_pro-0.1.0/src/mareforma_pro.egg-info/top_level.txt +1 -0
  32. mareforma_pro-0.1.0/tests/test_mareforma_pro_application.py +109 -0
  33. mareforma_pro-0.1.0/tests/test_mareforma_pro_cli.py +68 -0
  34. mareforma_pro-0.1.0/tests/test_mareforma_pro_fuse.py +190 -0
  35. mareforma_pro-0.1.0/tests/test_mareforma_pro_observe.py +222 -0
  36. mareforma_pro-0.1.0/tests/test_mareforma_pro_receipt.py +65 -0
  37. mareforma_pro-0.1.0/tests/test_mareforma_pro_runner.py +72 -0
  38. mareforma_pro-0.1.0/tests/test_mareforma_pro_server_otel.py +150 -0
  39. mareforma_pro-0.1.0/tests/test_mareforma_pro_strace.py +85 -0
  40. mareforma_pro-0.1.0/tests/test_package_metadata.py +31 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Felipe Yáñez
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,5 @@
1
+ graft tests
2
+ include README.md
3
+ include LICENSE
4
+ global-exclude *.py[cod]
5
+ prune tests/**/__pycache__
@@ -0,0 +1,100 @@
1
+ Metadata-Version: 2.4
2
+ Name: mareforma-pro
3
+ Version: 0.1.0
4
+ Summary: Rootless, no-sudo observation transports for Mareforma
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/mareforma/mareforma
7
+ Project-URL: Documentation, https://docs.mareforma.com
8
+ Project-URL: Repository, https://github.com/mareforma/mareforma
9
+ Project-URL: Issues, https://github.com/mareforma/mareforma/issues
10
+ Keywords: mareforma,provenance,grounding,rootless,fuse,strace
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: mareforma>=0.4.0
24
+ Requires-Dist: click>=8.1
25
+ Provides-Extra: otel
26
+ Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
27
+ Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=9.0.3; extra == "dev"
30
+ Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ # mareforma-pro
34
+
35
+ `mareforma-pro` is the independently released, no-`sudo` observation extension
36
+ for [Mareforma](https://github.com/mareforma/mareforma). It installs the import
37
+ package `mareforma_pro` and the `mareforma-pro` command.
38
+
39
+ ```bash
40
+ uv add mareforma-pro
41
+ ```
42
+
43
+ The distribution depends on the core `mareforma` package. Use it when the host
44
+ does not grant `sudo`, CAP_BPF, or a writable cgroup subtree.
45
+
46
+ Releases use the independent tag namespace `mareforma-pro-vX.Y.Z` and publish
47
+ only this project. Core `mareforma` releases keep the `vX.Y.Z` tag namespace.
48
+
49
+ ## Transports
50
+
51
+ - `strace + bwrap` (default): `strace --seccomp-bpf -f -y`, no privileged
52
+ daemon.
53
+ - `FUSE + bwrap` (alternate): a scope-specific read-only `/dev/fuse` view that
54
+ needs no ptrace. It uses the system `fusermount3` helper only for the
55
+ unprivileged mount and requires no extra Python package.
56
+
57
+ ```bash
58
+ # P1: ptrace-based read/open evidence
59
+ mareforma-pro run \
60
+ --secret "$MAREFORMA_HMAC_SECRET" \
61
+ --cite /data/exp42/results.csv \
62
+ --ro-bind /data/exp42:/tmp/work \
63
+ -- /bin/cat /tmp/work/results.csv
64
+
65
+ # P2: ptrace-free FUSE read evidence
66
+ mareforma-pro run-fuse \
67
+ --secret "$MAREFORMA_HMAC_SECRET" \
68
+ --source /data/exp42 \
69
+ --cite /data/exp42/results.csv \
70
+ -- /bin/cat /tmp/mareforma-data/results.csv
71
+ ```
72
+
73
+ Both transports sign a `mareforma_pro.rootless_receipt/v1` receipt. The SDK
74
+ parent verifies the HMAC and converts it into a normal Mareforma grounding
75
+ verdict. A citation outside a FUSE receipt's signed `coverage_roots` is
76
+ `OPAQUE(unmapped_sandbox_path)`, never a confident `UNGROUNDED`.
77
+
78
+ ## Python
79
+
80
+ ```python
81
+ from mareforma_pro import RootlessCollector, RootlessFuseRunner, verify_and_verdict
82
+
83
+ collector = RootlessCollector(secret)
84
+ run = RootlessFuseRunner(collector).run_in_bwrap(
85
+ ["/bin/cat", "/tmp/mareforma-data/results.csv"],
86
+ source_root="/data/exp42",
87
+ )
88
+ verdict = verify_and_verdict(
89
+ run.evidence.to_receipt_dict(),
90
+ secret=secret,
91
+ cites="/data/exp42/results.csv",
92
+ )
93
+ ```
94
+
95
+ HMAC authenticates a receipt across the local process boundary. It is not a
96
+ defense against code that can read the parent's secret. Keep the secret out of
97
+ the target environment; the runners use `bwrap --clearenv` by default.
98
+
99
+ The optional OTLP adapter is available as `mareforma-pro[otel]`; the JSONL
100
+ exporter and span projection use only the standard library.
@@ -0,0 +1,68 @@
1
+ # mareforma-pro
2
+
3
+ `mareforma-pro` is the independently released, no-`sudo` observation extension
4
+ for [Mareforma](https://github.com/mareforma/mareforma). It installs the import
5
+ package `mareforma_pro` and the `mareforma-pro` command.
6
+
7
+ ```bash
8
+ uv add mareforma-pro
9
+ ```
10
+
11
+ The distribution depends on the core `mareforma` package. Use it when the host
12
+ does not grant `sudo`, CAP_BPF, or a writable cgroup subtree.
13
+
14
+ Releases use the independent tag namespace `mareforma-pro-vX.Y.Z` and publish
15
+ only this project. Core `mareforma` releases keep the `vX.Y.Z` tag namespace.
16
+
17
+ ## Transports
18
+
19
+ - `strace + bwrap` (default): `strace --seccomp-bpf -f -y`, no privileged
20
+ daemon.
21
+ - `FUSE + bwrap` (alternate): a scope-specific read-only `/dev/fuse` view that
22
+ needs no ptrace. It uses the system `fusermount3` helper only for the
23
+ unprivileged mount and requires no extra Python package.
24
+
25
+ ```bash
26
+ # P1: ptrace-based read/open evidence
27
+ mareforma-pro run \
28
+ --secret "$MAREFORMA_HMAC_SECRET" \
29
+ --cite /data/exp42/results.csv \
30
+ --ro-bind /data/exp42:/tmp/work \
31
+ -- /bin/cat /tmp/work/results.csv
32
+
33
+ # P2: ptrace-free FUSE read evidence
34
+ mareforma-pro run-fuse \
35
+ --secret "$MAREFORMA_HMAC_SECRET" \
36
+ --source /data/exp42 \
37
+ --cite /data/exp42/results.csv \
38
+ -- /bin/cat /tmp/mareforma-data/results.csv
39
+ ```
40
+
41
+ Both transports sign a `mareforma_pro.rootless_receipt/v1` receipt. The SDK
42
+ parent verifies the HMAC and converts it into a normal Mareforma grounding
43
+ verdict. A citation outside a FUSE receipt's signed `coverage_roots` is
44
+ `OPAQUE(unmapped_sandbox_path)`, never a confident `UNGROUNDED`.
45
+
46
+ ## Python
47
+
48
+ ```python
49
+ from mareforma_pro import RootlessCollector, RootlessFuseRunner, verify_and_verdict
50
+
51
+ collector = RootlessCollector(secret)
52
+ run = RootlessFuseRunner(collector).run_in_bwrap(
53
+ ["/bin/cat", "/tmp/mareforma-data/results.csv"],
54
+ source_root="/data/exp42",
55
+ )
56
+ verdict = verify_and_verdict(
57
+ run.evidence.to_receipt_dict(),
58
+ secret=secret,
59
+ cites="/data/exp42/results.csv",
60
+ )
61
+ ```
62
+
63
+ HMAC authenticates a receipt across the local process boundary. It is not a
64
+ defense against code that can read the parent's secret. Keep the secret out of
65
+ the target environment; the runners use `bwrap --clearenv` by default.
66
+
67
+ The optional OTLP adapter is available as `mareforma-pro[otel]`; the JSONL
68
+ exporter and span projection use only the standard library.
@@ -0,0 +1,69 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "mareforma-pro"
7
+ version = "0.1.0"
8
+ description = "Rootless, no-sudo observation transports for Mareforma"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ keywords = ["mareforma", "provenance", "grounding", "rootless", "fuse", "strace"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Intended Audience :: Science/Research",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.10",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Programming Language :: Python :: 3.14",
23
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
24
+ ]
25
+ dependencies = [
26
+ "mareforma>=0.4.0",
27
+ "click>=8.1",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ # Optional OTLP/HTTP transport. The built-in JSONL exporter and span
32
+ # projection use only the standard library.
33
+ otel = [
34
+ "opentelemetry-sdk>=1.20",
35
+ "opentelemetry-exporter-otlp-proto-http>=1.20",
36
+ ]
37
+ # Editable development and tests for this distribution on its own.
38
+ dev = [
39
+ "pytest>=9.0.3",
40
+ "tomli>=2.0; python_version < '3.11'",
41
+ ]
42
+
43
+ [project.urls]
44
+ Homepage = "https://github.com/mareforma/mareforma"
45
+ Documentation = "https://docs.mareforma.com"
46
+ Repository = "https://github.com/mareforma/mareforma"
47
+ Issues = "https://github.com/mareforma/mareforma/issues"
48
+
49
+ [project.scripts]
50
+ mareforma-pro = "mareforma_pro.cli:cli"
51
+
52
+ [tool.setuptools.packages.find]
53
+ where = ["src"]
54
+ include = ["mareforma_pro", "mareforma_pro.*"]
55
+
56
+ [tool.setuptools.package-data]
57
+ mareforma_pro = ["py.typed"]
58
+
59
+ [tool.pytest.ini_options]
60
+ testpaths = ["tests"]
61
+ pythonpath = ["src"]
62
+ addopts = "-v --tb=short --strict-markers"
63
+ markers = [
64
+ "rootless: requires strace, bwrap, /dev/fuse, or another host primitive",
65
+ ]
66
+
67
+ [tool.coverage.run]
68
+ source = ["mareforma_pro"]
69
+ omit = ["tests/*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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]