agentboxx 0.2.1__py3-none-any.whl

agentbox/signer.py

@@ -0,0 +1,148 @@
+"""Tamper-evident event log: every record is hash-chained and HMAC-signed."""
+import hashlib
+import hmac
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+
+GENESIS = "0" * 64
+
+
+def canon(obj) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def _sha(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def load_or_create_key(path=None) -> bytes:
+    path = Path(path or Path.home() / ".agentbox" / "key")
+    if path.exists():
+        return bytes.fromhex(path.read_text().strip())
+    path.parent.mkdir(parents=True, exist_ok=True)
+    key = os.urandom(32)
+    path.write_text(key.hex())
+    path.chmod(0o600)
+    return key
+
+
+class ChainWriter:
+    def __init__(self, path, key: bytes, overwrite: bool = False):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if self.path.exists() and self.path.stat().st_size > 0:
+            if not overwrite:
+                raise FileExistsError(
+                    f"Log already exists: {self.path}. Use a new session id or pass overwrite=True.")
+            self.path.write_text("")
+        manifest_path(self.path).unlink(missing_ok=True)   # never keep a stale manifest
+        self.key, self.seq, self.prev = key, 0, GENESIS
+
+    def write_manifest(self):
+        """Write the signed closing manifest. Call after the final record."""
+        write_manifest(self.path, self.key, self.seq, self.prev)
+
+    def append(self, event_type: str, data: dict) -> dict:
+        self.seq += 1
+        event = {
+            "schema_version": "0.1",
+            "event_id": str(uuid.uuid4()),
+            "event_type": event_type,
+            "ts": time.time(),
+            "seq": self.seq,
+            "data": data,
+        }
+        chain_hash = _sha((self.prev + _sha(canon(event))).encode())
+        sig = hmac.new(self.key, chain_hash.encode(), hashlib.sha256).hexdigest()
+        record = {"event": event, "prev_hash": self.prev, "hash": chain_hash, "sig": sig}
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+            f.flush()
+            os.fsync(f.fileno())
+        self.prev = chain_hash
+        return record
+
+
+def verify_file(path, key: bytes) -> list[str]:
+    """Return a list of problems. Empty list = log is intact."""
+    problems, prev, expected = [], GENESIS, 1
+    with open(path, encoding="utf-8") as f:
+        for n, line in enumerate(f, 1):
+            try:
+                rec = json.loads(line)
+                ev = rec["event"]
+            except (json.JSONDecodeError, KeyError):
+                problems.append(f"line {n}: unreadable record")
+                continue
+            if ev["seq"] != expected:
+                problems.append(f"line {n}: sequence gap (expected {expected}, got {ev['seq']})")
+            expected = ev["seq"] + 1
+            if rec["prev_hash"] != prev:
+                problems.append(f"line {n}: chain broken")
+            good = _sha((rec["prev_hash"] + _sha(canon(ev))).encode())
+            if good != rec["hash"]:
+                problems.append(f"line {n}: content was modified")
+            want = hmac.new(key, rec["hash"].encode(), hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(want, rec["sig"]):
+                problems.append(f"line {n}: bad signature")
+            prev = rec["hash"]
+    return problems
+
+
+def manifest_path(log_path) -> Path:
+    p = Path(log_path)
+    return p.with_name(p.stem + ".manifest.json")
+
+
+def write_manifest(log_path, key: bytes, records: int, final_hash: str):
+    """Signed summary written when a session closes: record count and last hash."""
+    payload = {"log": Path(log_path).name, "records": records, "final_hash": final_hash}
+    sig = hmac.new(key, canon(payload), hashlib.sha256).hexdigest()
+    manifest_path(log_path).write_text(
+        json.dumps({"payload": payload, "sig": sig}, indent=2), encoding="utf-8")
+
+
+def verify_log(path, key: bytes):
+    """Full check. Returns (problems, incomplete).
+
+    problems   = evidence of tampering (bad chain or signature, or the log does
+                 not match its signed manifest, e.g. the end was cut off).
+    incomplete = the log is intact so far but was never closed, or its end is
+                 missing: a crash, a running session, or a removed tail.
+    """
+    problems = verify_file(path, key)
+    last = {}
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            try:
+                rec = json.loads(line)
+                last = {"seq": rec["event"]["seq"], "hash": rec["hash"],
+                        "type": rec["event"]["event_type"]}
+            except (ValueError, KeyError, TypeError):
+                continue
+    incomplete = []
+    mp = manifest_path(path)
+    if mp.exists():
+        try:
+            m = json.loads(mp.read_text(encoding="utf-8"))
+            payload, sig = m["payload"], m["sig"]
+            want = hmac.new(key, canon(payload), hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(want, sig):
+                problems.append("manifest signature is invalid")
+            elif last.get("seq") != payload["records"] or last.get("hash") != payload["final_hash"]:
+                problems.append(
+                    f"log does not match its signed manifest (expected {payload['records']} "
+                    f"records ending in {payload['final_hash'][:12]}): truncated or modified")
+        except (OSError, ValueError, KeyError, TypeError):
+            problems.append("manifest is unreadable")
+    else:
+        if last.get("type") != "session.end":
+            incomplete.append("no session.end record and no manifest: the session crashed, "
+                              "is still running, or the end of the log was removed")
+        else:
+            incomplete.append("session is closed but its manifest is missing: "
+                              "the manifest may have been deleted")
+    return problems, incomplete

agentbox/streaming.py

@@ -0,0 +1,133 @@
+"""Run a command with bounded memory, a hard deadline, and a whole-tree kill.
+
+Why this exists: subprocess.run(capture_output=True) keeps all output in memory
+(a command that prints gigabytes can exhaust the host), and a timeout only
+kills the direct child, leaving anything it started running.
+"""
+import os
+import re
+import signal
+import subprocess
+import threading
+import time
+
+HEAD_BYTES = 1900
+TAIL_BYTES = 1900
+DEFAULT_MAX_STREAM_BYTES = 10 * 1024 * 1024   # per stream (stdout, stderr)
+_MAX_CUT_TOKEN = 512
+
+
+class Capture:
+    """Keeps the first HEAD_BYTES and last TAIL_BYTES of a stream, plus its total size."""
+
+    def __init__(self, head: int = HEAD_BYTES, tail: int = TAIL_BYTES):
+        self._head_n, self._tail_n = head, tail
+        self._head, self._tail = bytearray(), bytearray()
+        self.total = 0
+
+    def feed(self, chunk: bytes):
+        self.total += len(chunk)
+        if len(self._head) < self._head_n:
+            take = self._head_n - len(self._head)
+            self._head += chunk[:take]
+            chunk = chunk[take:]
+        if chunk:
+            self._tail += chunk
+            if len(self._tail) > self._tail_n:
+                del self._tail[: len(self._tail) - self._tail_n]
+
+    @property
+    def truncated(self) -> bool:
+        return self.total > len(self._head) + len(self._tail)
+
+    def text(self) -> str:
+        head = bytes(self._head).decode("utf-8", "replace")
+        tail = bytes(self._tail).decode("utf-8", "replace")
+        if not self.truncated:
+            return head + tail
+        # A cut can land inside a token. Drop the partial token at each cut so a
+        # secret is never left half-visible (redaction needs the whole token).
+        m = re.search(r"\S+\Z", head)
+        if m and len(m.group()) <= _MAX_CUT_TOKEN:
+            head = head[: m.start()]
+        m = re.match(r"\S+", tail)
+        if m and len(m.group()) <= _MAX_CUT_TOKEN:
+            tail = tail[m.end():]
+        omitted = self.total - len(self._head) - len(self._tail)
+        return f"{head}\n...[{omitted} bytes omitted]...\n{tail}"
+
+
+def kill_tree(proc: subprocess.Popen):
+    """SIGKILL the command's whole process group (it was started in its own session)."""
+    try:
+        if os.name == "posix":
+            os.killpg(proc.pid, signal.SIGKILL)
+        else:
+            proc.kill()
+    except OSError:
+        pass
+
+
+def run_streaming(argv, cwd, timeout_s, max_bytes=DEFAULT_MAX_STREAM_BYTES, cleanup=None):
+    """Run argv. Returns (exit_code, stdout_capture, stderr_capture, timed_out, output_exceeded).
+
+    On timeout, or when either stream passes max_bytes, the whole process group is
+    killed and cleanup() (if given) is called. Exit codes: 124 timeout, 137 output cap.
+    """
+    out, err = Capture(), Capture()
+    kwargs = {"cwd": cwd, "stdin": subprocess.DEVNULL,
+              "stdout": subprocess.PIPE, "stderr": subprocess.PIPE}
+    if os.name == "posix":
+        kwargs["start_new_session"] = True
+    proc = subprocess.Popen(argv, **kwargs)
+    exceeded = threading.Event()
+
+    def pump(stream, cap):
+        try:
+            while True:
+                chunk = stream.read1(65536)
+                if not chunk:
+                    return
+                cap.feed(chunk)
+                if cap.total > max_bytes:
+                    exceeded.set()
+                    return
+        except (OSError, ValueError):
+            return
+
+    threads = [threading.Thread(target=pump, args=(proc.stdout, out), daemon=True),
+               threading.Thread(target=pump, args=(proc.stderr, err), daemon=True)]
+    for t in threads:
+        t.start()
+
+    deadline = time.monotonic() + timeout_s
+    timed_out = False
+    while True:
+        if exceeded.is_set():
+            break
+        if proc.poll() is not None and not any(t.is_alive() for t in threads):
+            break
+        if time.monotonic() >= deadline:
+            timed_out = True
+            break
+        time.sleep(0.01)
+
+    if exceeded.is_set() or timed_out:
+        kill_tree(proc)
+        if cleanup:
+            cleanup()
+    proc.wait()
+    for t in threads:
+        t.join(timeout=2)
+    for s in (proc.stdout, proc.stderr):
+        try:
+            s.close()
+        except OSError:
+            pass
+
+    code = proc.returncode
+    if timed_out:
+        code = 124
+    elif exceeded.is_set():
+        code = 137
+    return code, out, err, timed_out, exceeded.is_set()

agentbox/workspace.py

@@ -0,0 +1,83 @@
+"""Hash a workspace directory so the loop detector can tell whether files changed.
+
+Properties: symlinks are recorded but never followed, special files (pipes, sockets)
+are never opened, big files are hashed by size and mtime instead of content, and
+unchanged files are not re-read between steps. Not thread-safe (module-level cache).
+"""
+import hashlib
+import os
+import stat
+import time
+
+DEFAULT_IGNORE = frozenset({".git", "__pycache__", "node_modules", ".venv",
+                            ".pytest_cache", ".mypy_cache", ".ruff_cache"})
+MAX_HASH_BYTES = 5 * 1024 * 1024        # larger files are hashed by size + mtime
+_RACY_NS = 2_000_000_000                # trust a cached digest only for files older than 2 s
+_CACHE: dict = {}                       # full path -> (size, mtime_ns, cached_at_ns, digest)
+
+
+def _sha_file(path: str):
+    h = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                h.update(chunk)
+    except OSError:
+        return None
+    return h.hexdigest()
+
+
+def _entry(full: str, rel: str, max_file_bytes: int, use_cache: bool, now: int, seen: dict) -> bytes:
+    try:
+        st = os.lstat(full)
+    except OSError:
+        return f"X:{rel}\n".encode()
+    if stat.S_ISLNK(st.st_mode):
+        try:
+            target = os.readlink(full)
+        except OSError:
+            target = "?"
+        return f"L:{rel}:{target}\n".encode()
+    if not stat.S_ISREG(st.st_mode):
+        return f"S:{rel}\n".encode()    # never open FIFOs, sockets or devices: open() could block
+    if st.st_size > max_file_bytes:
+        return f"B:{rel}:{st.st_size}:{st.st_mtime_ns}\n".encode()
+    cached = _CACHE.get(full) if use_cache else None
+    if (cached and cached[0] == st.st_size and cached[1] == st.st_mtime_ns
+            and cached[1] + _RACY_NS <= cached[2]):
+        entry = cached
+    else:
+        digest = _sha_file(full)
+        if digest is None:
+            return f"X:{rel}\n".encode()
+        entry = (st.st_size, st.st_mtime_ns, now, digest)
+    seen[full] = entry
+    return f"F:{rel}:{entry[3]}\n".encode()
+
+
+def workspace_hash(root: str, ignore=None, max_file_bytes: int = MAX_HASH_BYTES,
+                   use_cache: bool = True) -> str:
+    """Short hash of the workspace. Changes when files are added, removed or modified."""
+    ignore = DEFAULT_IGNORE if ignore is None else frozenset(ignore)
+    root = os.path.abspath(root)
+    now = time.time_ns()
+    seen: dict = {}
+    h = hashlib.sha256()
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(d for d in dirnames if d not in ignore)
+        for d in list(dirnames):            # symlinked directories are listed but never entered
+            full = os.path.join(dirpath, d)
+            if os.path.islink(full):
+                dirnames.remove(d)
+                rel = os.path.relpath(full, root).replace(os.sep, "/")
+                h.update(_entry(full, rel, max_file_bytes, use_cache, now, seen))
+        for name in sorted(filenames):
+            full = os.path.join(dirpath, name)
+            rel = os.path.relpath(full, root).replace(os.sep, "/")
+            h.update(_entry(full, rel, max_file_bytes, use_cache, now, seen))
+    if use_cache:
+        prefix = root + os.sep
+        for k in [k for k in _CACHE if k.startswith(prefix) and k not in seen]:
+            del _CACHE[k]
+        _CACHE.update(seen)
+    return h.hexdigest()[:16]

agentboxx-0.2.1.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: agentboxx
+Version: 0.2.1
+Summary: A tamper-evident flight recorder for AI agents
+Author-email: Prathmesh Kokate <prathmeshkokate775@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Prathmesh010190/Agentboxx
+Project-URL: Repository, https://github.com/Prathmesh010190/Agentboxx
+Project-URL: Issues, https://github.com/Prathmesh010190/Agentboxx/issues
+Project-URL: Documentation, https://github.com/Prathmesh010190/Agentboxx/tree/main/docs
+Keywords: ai,agents,security,audit,flight-recorder,tamper-evident,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# agentbox
+
+**A tamper-evident flight recorder for AI agents.**
+
+Run agent commands in an isolated sandbox, record what actually happened, sign every record, and catch agents that get stuck.
+
+[![CI](https://github.com/Prathmesh010190/Agentboxx/actions/workflows/ci.yml/badge.svg)](https://github.com/Prathmesh010190/Agentboxx/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)
+![Status](https://img.shields.io/badge/status-MVP-green.svg)
+
+</div>
+
+> [!NOTE]
+> **v0.2 MVP.** Working prototype validated end-to-end with sandboxed execution, cryptographic signing, loop detection, and live model execution. Interfaces may evolve before v1.0. Known gaps are listed under [Limitations](#limitations).
+
+---
+
+## Why agentbox
+
+Most agent tooling records what the agent *says* it did, from inside the agent's own process. agentbox observes from the outside.
+
+| | What it gives you |
+|---|---|
+| **Host-side capture** | Output, exit codes and timing are recorded by the host, not reported by the agent. |
+| **Tamper-evident logs** | Every record is hash-chained and HMAC-signed with a key that never enters the sandbox. Edits, deletions and reordering are detected by `agentbox verify`. |
+| **State-aware loop detection** | A repeated command only counts when the workspace did not change, which separates retrying from making progress. |
+| **Hint feedback** | When the detector fires, a hint is added to the agent's next observation so it can change approach. |
+| **Hardened sandbox** | Docker backend with no network, read-only root filesystem, dropped capabilities, non-root user and resource limits. |
+
+## Architecture
+
+<p align="center">
+  <img src="docs/architecture.svg" alt="agentbox architecture: model, Docker sandbox, recorder, signed log, and loop detector feeding hints back to the model" width="900">
+</p>
+
+| Module | Role |
+|---|---|
+| `signer.py` | Hash-chained, HMAC-signed event log and `verify_file` |
+| `executor.py` | Local command runner, error fingerprints, workspace hashing |
+| `docker_backend.py` | Runs commands in a locked-down container |
+| `loop_detector.py` | Exact repeat, repeated error, no-progress and cycle detection |
+| `recorder.py` | Main API: `Recorder.run(command)` |
+| `agent.py` | Minimal ReAct-style loop that feeds detector hints back to the model |
+
+## Quick start
+
+Requires Python 3.10+. Docker is optional and used by the sandbox demos.
+
+~~~bash
+pip install agentboxx
+~~~
+
+Or install from source:
+
+~~~bash
+git clone https://github.com/Prathmesh010190/Agentboxx.git
+cd Agentboxx
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+~~~
+
+Try it with one command (no Docker, no API key, nothing left behind):
+
+~~~bash
+agentbox demo
+~~~
+
+Run the demos from the repo:
+
+~~~bash
+python examples/demo_agent.py            # stuck-agent demo (local backend)
+python examples/demo_docker.py           # shows what the Docker sandbox blocks
+python examples/demo_agent_loop.py       # full pipeline: detect, hint, recover
+
+agentbox report runs/agent-demo.ndjson   # readable summary
+agentbox verify runs/agent-demo.ndjson   # integrity check
+agentbox list                            # every log in ./runs: session, start time, steps, verifies?
+agentbox --version
+~~~
+
+`report` uses color for errors and warnings when writing to a terminal. Set `NO_COLOR=1` to turn it off. It supports `--format text|json|html` (default: `text`) and `--output <file>` (or `-o`) to export reports; HTML reports are completely self-contained with no external assets.
+
+### Example: a stuck agent recovers
+
+The scripted agent repeats a failing command. After the third identical failure on an unchanged workspace, the detector raises warnings and the next observation carries a hint:
+
+~~~text
+[2] Run it.
+    $ python3 main.py  -> exit 1
+[3] Run it.
+    $ python3 main.py  -> exit 1
+[4] Run it.
+    $ python3 main.py  -> exit 1
+    !! warn: loop.exact
+    !! warn: loop.error_repeat
+    !! warn: loop.no_progress
+[5] The hint is right: x = 0 causes the crash. Fix the value.
+    $ sed -i 's/x = 0/x = 2/' main.py  -> exit 0
+[6] Run it again.
+    $ python3 main.py  -> exit 0
+
+Result: {'reason': 'final_answer', 'final': 'Fixed the divide-by-zero; script prints 5.0.'}
+~~~
+
+### Example: tamper detection
+
+Change any value in a log file and verification fails:
+
+~~~text
+$ agentbox verify runs/demo.ndjson
+LOG HAS BEEN TAMPERED WITH OR IS CORRUPT:
+  - line 3: content was modified
+~~~
+
+## Use it in your own agent
+
+~~~python
+from agentbox import Recorder
+from agentbox.docker_backend import DockerSandbox
+
+sandbox = DockerSandbox("./workspace")   # no network by default
+sandbox.start()
+rec = Recorder("my-session", workspace="./workspace", sandbox=sandbox)
+
+result = rec.run("pytest -x", thought="Run the tests")
+print(result["signals"])                 # loop warnings, if any
+
+rec.close("done")                        # also stops the container
+~~~
+
+`agentbox.agent.run_agent` wraps this in a ReAct-style loop. `ScriptedModel` needs no API key. `GeminiModel` connects to Google Gemini via standard-library REST (needs `GEMINI_API_KEY`, validated end-to-end). `AnthropicModel` is an optional adapter (`pip install anthropic`, set `ANTHROPIC_API_KEY`).
+
+## What `agentbox verify` reports
+
+| Result | Exit code | Meaning |
+|---|---|---|
+| `OK` | 0 | Chain, signatures and the closing manifest all match |
+| `TAMPERED` | 1 | A record was edited, removed or reordered, or the log no longer matches its signed manifest |
+| `INCOMPLETE` | 2 | The log is intact so far but was never closed: a crash, a running session, or a removed tail |
+| *(error)* | 3 | The file is missing, empty, a directory or unreadable. This is not a verdict on the log, and `report` uses the same code |
+
+The manifest (`<session>.manifest.json`) is written when a session closes and records the final record count and hash, signed with the same key. The verifier requires the manifest: a closed session whose manifest is missing is reported as `INCOMPLETE`, and a truncated log whose manifest is still present is reported as `TAMPERED`. Anyone who can read the signing key can forge both files, so copy manifests somewhere the agent host cannot write to if that matters. Public-key signing, as used for Nanda Town's evidence attestations, would let third parties verify logs without holding a secret, and is a possible future change.
+
+## Detection signals
+
+| Signal | Meaning |
+|---|---|
+| `loop.exact` | The same command was repeated on an unchanged workspace |
+| `loop.error_repeat` | The same normalized error keeps recurring |
+| `loop.no_progress` | Several steps failed while no files changed |
+| `loop.cycle` | The agent alternates between the same few commands |
+
+Warnings become hints for the model. Critical severity (for example five identical repeats) stops the run.
+
+## Sandbox resource and crash events
+
+With the Docker backend, the host records two extra signed events after each step: `sandbox.resource` (memory, CPU, process count) and `sandbox.crash` (an out-of-memory kill, or a container that stopped). Everything is read on the host through Docker, so the agent cannot influence it.
+
+- Resource sampling adds about a second per step. Turn it off with `DockerSandbox(resource_stats=False)`.
+- A sample is a snapshot after the step, not a peak.
+- The local backend has no equivalent, and `agentbox report` does not show these events yet.
+
+## Error signatures
+
+Repeated-error detection compares normalized error signatures, so the same failure matches even when line numbers, file paths or runtime versions differ.
+
+| Language | Recognized output | Signature class |
+|---|---|---|
+| Python | Tracebacks | Exception name, e.g. `ZeroDivisionError` |
+| Node.js | Uncaught errors with stack frames | e.g. `TypeError`, `Error[ERR_MODULE_NOT_FOUND]` |
+| Go | Panics, fatal errors, compile errors | `GoPanic`, `GoFatalError`, `GoCompileError` |
+
+Anything else falls back to hashing the last lines of stderr. To add a language, see `src/agentbox/error_signatures.py`.
+
+## Secret redaction
+
+Commands, output and the model's reasoning are redacted **before** they are signed, because a signed record cannot be edited afterward. Recognized: private key blocks, AWS, GitHub, Slack and Google keys, `sk-` style API keys, JWTs, `Authorization` headers, passwords in URLs, and `NAME=value` where the name contains `password`, `secret`, `token` or `api_key`. Each step records only a count per pattern, never the value.
+
+Limits to know about:
+- Patterns are heuristics. They miss some secrets (for example a secret with no recognizable name or format) and sometimes hide harmless values such as a long `*_token=` setting.
+- The command itself still runs with the real value. Only the **record** is redacted.
+- With the agent loop, the model also receives the redacted output, so it cannot read a secret that a command printed.
+- Files in the workspace are not logged, but anything a command prints from them is covered by these patterns only.
+- Add your own patterns with `agentbox.redact.add_pattern(name, regex)`.
+
+## Log format
+
+The log format is documented in [docs/log-format.md](docs/log-format.md) and described by JSON Schemas ([record](docs/schema.json), [manifest](docs/manifest.schema.json)). [examples/verify_standalone.py](examples/verify_standalone.py) verifies a log using only the Python standard library, as an independent check that the spec is complete.
+
+## Threat model
+
+- **Docker backend:** commands run as a non-root user in a container with no network, a read-only root filesystem, all Linux capabilities dropped, `no-new-privileges`, and CPU, memory and process limits. The signing key and logs stay on the host and are never mounted into the container.
+- **Local backend:** no isolation. The agent runs as your user and could read the signing key. Use it only for trusted experiments.
+- Docker isolation is strong but not a perfect boundary. Run untrusted agents in a disposable VM.
+- The log shows that records were not altered after writing. It does not prove the agent's intent, and it cannot see anything that bypasses the executor.
+
+## Limitations
+
+- Windows is experimental. The Docker backend no longer needs Unix user IDs and runs as user `1000:1000` in the container (override with `DockerSandbox(user=...)`), but it has not been run on real Windows hardware yet. It needs Docker Desktop with Linux containers. The local backend still needs `bash` (Git Bash), and on Windows a timeout kills only the direct child process.
+- Detector thresholds are initial values, not calibrated on real agent traces.
+- No network capture yet (the sandbox simply has no network).
+- No semantic drift detection yet; detection is command and state based.
+- Error signatures cover Python, Node.js and Go only. Other languages use a generic fallback.
+
+## Roadmap
+
+- [x] Signed, hash-chained event log with verification
+- [x] Docker sandbox backend
+- [x] Loop detection with hint feedback
+- [x] ReAct-style agent loop
+- [x] Stable error signatures for Python, Node.js and Go
+- [x] Truncation detection with a signed closing manifest
+- [x] Secret redaction before signing
+- [ ] Output size cap and process-tree kill on timeout
+- [x] Sandbox resource and crash events (Docker backend)
+- [ ] Public-key signing so third parties can verify logs
+- [x] Validate against a live model ([#5](https://github.com/Prathmesh010190/Agentboxx/issues/5))
+- [ ] Network egress capture (design in [docs/network-egress.md](docs/network-egress.md))
+- [ ] Semantic drift detector
+- [ ] Session replay UI
+- [ ] Threshold calibration on recorded sessions
+
+## Contributing
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the issues labeled [`good first issue`](https://github.com/Prathmesh010190/Agentboxx/labels/good%20first%20issue).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

agentboxx-0.2.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+agentbox/__init__.py,sha256=dYEww15gZh1FGuOR9ztShNQ06rhaEL-qcrwFDQUNreA,220
+agentbox/agent.py,sha256=XhtzisW1i7BSxmwgjpBWbrwP40onT2yQzRrNSq8g5MU,5646
+agentbox/cli.py,sha256=kOEN-zHD1-kbYXING7epS5H28oSoO_mflQAnVVITd_Q,9433
+agentbox/docker_backend.py,sha256=vzfajjygGtUdBMZlE8-s9W_y-_ljix8-7I4fKV0-WpY,7271
+agentbox/error_signatures.py,sha256=Tk1N9L6i6lMuRySPxuqorB3Fr4sgNZwwIJF-M6bsdn4,1638
+agentbox/executor.py,sha256=X32Mr2hfW_DtHWP0u-jV-bPDY5J0Q_PLgpwcH6nIu80,3600
+agentbox/loop_detector.py,sha256=OzdtDw6vI-iDVqMH_zv2wkAtrJ2aPGx2mvGDx7y6Nj0,2742
+agentbox/recorder.py,sha256=tGs_LmaOpjfaIzdL_uRnKY6WO7ZQcSji0RJHXqWmNpI,3437
+agentbox/redact.py,sha256=gil6859clHOAEIaTkdxtnY15AzJz83uUQ2bbxNWd0hI,2925
+agentbox/report.py,sha256=rWz2Sf6TR0iWub7WXX7TRbm5mobEF3dNAcsQbUvW3z8,12063
+agentbox/sandbox_stats.py,sha256=dsOPcbm1ZwpWqdANdPval4WPCaq3lu2YSQzuwFBkBp0,2423
+agentbox/signer.py,sha256=3DVrblKCVnf6FL8tbGHJ4Y02lC1YtJ345OaqFN9ZYC0,6041
+agentbox/streaming.py,sha256=yMzwH_jS_Fq0gb9MOHPZBV3zhBoR45KD80QUFKY_kVY,4406
+agentbox/workspace.py,sha256=Bw7kPC-lRtREAYbzE7TYlm-xVbEDesAlGTltuVMomsE,3470
+agentboxx-0.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+agentboxx-0.2.1.dist-info/METADATA,sha256=nbRZNqzAVqdEeHZIswtdCfxcXv31yji93RwihSl4HiQ,13323
+agentboxx-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agentboxx-0.2.1.dist-info/entry_points.txt,sha256=u_320LVs7Vndr2ti0gFQXhR8o9kkjW0LmNjLzEXLr50,47
+agentboxx-0.2.1.dist-info/top_level.txt,sha256=lNpen_9W4iU-XQIGpizrWb3jS7tj6k27fUBWT4u0HEQ,9
+agentboxx-0.2.1.dist-info/RECORD,,

agentboxx-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentboxx-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentbox = agentbox.cli:main