aegis-sandbox 0.8.0__tar.gz

aegis_sandbox-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adarsh14734
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aegis_sandbox-0.8.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: aegis-sandbox
+Version: 0.8.0
+Summary: MCP-layer policy proxy with a tamper-evident audit trail
+Author: Adarsh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Adarsh14734/Aegis
+Keywords: mcp,policy,audit,agent,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: keyring
+Requires-Dist: keyring>=24; extra == "keyring"
+Dynamic: license-file
+
+# Aegis
+
+**Claude Code's sandbox lets an agent read your SSH keys and AWS credentials by default. Aegis doesn't.**
+
+Two layers, both verified on real hardware.
+
+Kernel sandbox — the agent's own shell cannot reach a denied path:
+
+    $ ! cat ~/.ssh/id_rsa
+    cat: /Users/you/.ssh/id_rsa: Operation not permitted
+
+    $ ! cat ~/.aws/credentials
+    cat: /Users/you/.aws/credentials: Operation not permitted
+
+    $ tail ~/Library/Application\ Support/Aegis/denials.log
+    kernel denied file-read-data /Users/you/.ssh/id_rsa to cat(pid 41560)
+    kernel denied file-read-data /Users/you/.aws/credentials to cat(pid 42180)
+
+MCP proxy — same tool, same file, with and without Aegis in front:
+
+    direct to the server:   allowed: TOKEN=proof-env-secret
+    through aegis proxy:    AEGIS DENIED: read_text_file
+                            Reason: path matches deny rule '.env'
+                            Rule: deny_paths
+
+## What it does
+
+Sits between your AI coding agent and your machine:
+
+- **Deny by default** on every tool call
+- **Kernel sandbox** on subprocesses — `cat .env` can't bypass it
+- **Tamper-evident audit log** — hash-chained, integrity checked by `aegis doctor`, and checkpointed
+  from outside the sandbox under a key the sandbox can't read or write
+- **Outbound requests checked** before they're made
+- **Secrets never reach the MCP server**
+
+## Install (macOS Apple Silicon)
+
+New here? [docs/getting-started.md](docs/getting-started.md) is the step-by-step path, including the two questions that default to No.
+
+    python3 -m pip install aegis-sandbox
+    aegis init      # detects Claude Code / Cursor, asks a few questions
+    aegis doctor    # proves the boundary is actually in place
+
+**Upgrading?** Re-run `aegis init`. Your `policy.json` is yours and is never rewritten behind your back, so a
+new sandbox domain does not appear on its own — and without the OAuth token endpoint a sandboxed client stops
+working when its token expires. `aegis init` offers the new hosts; accepting is one keystroke.
+
+Prefer an app? [Download the .dmg](https://github.com/Adarsh14734/Aegis/releases/download/v0.6.0/Aegis_0.6.0_aarch64.dmg)
+
+`SHA256: bcccaa957fd3a0a15413eb1207a012f0328e309d078e7b7f2af853915e64c6dc`
+
+Unsigned build — right-click the app → Open the first time (macOS will warn about an unidentified developer, that's expected). Or build from source.
+
+## What it does NOT do
+
+- Does not stop prompt injection
+- Kernel escape defeats the sandbox
+- The audit database is still writable from inside the sandbox. Checkpoints make tampering with
+  *already-checkpointed* history detectable — not impossible, and the newest rows aren't covered yet
+- A sandboxed client can't renew an expired login token — run it once outside the sandbox to refresh
+- The sandbox can still *read* your OAuth token from the Keychain
+- Tool results larger than 16 MiB are refused
+- No external security review, no certifications
+- Not audited by anyone but me — read the source, that's why it's MIT
+
+Full threat model: THREAT-MODEL.md
+
+## License
+
+MIT

aegis_sandbox-0.8.0/README.md

@@ -0,0 +1,71 @@
+# Aegis
+
+**Claude Code's sandbox lets an agent read your SSH keys and AWS credentials by default. Aegis doesn't.**
+
+Two layers, both verified on real hardware.
+
+Kernel sandbox — the agent's own shell cannot reach a denied path:
+
+    $ ! cat ~/.ssh/id_rsa
+    cat: /Users/you/.ssh/id_rsa: Operation not permitted
+
+    $ ! cat ~/.aws/credentials
+    cat: /Users/you/.aws/credentials: Operation not permitted
+
+    $ tail ~/Library/Application\ Support/Aegis/denials.log
+    kernel denied file-read-data /Users/you/.ssh/id_rsa to cat(pid 41560)
+    kernel denied file-read-data /Users/you/.aws/credentials to cat(pid 42180)
+
+MCP proxy — same tool, same file, with and without Aegis in front:
+
+    direct to the server:   allowed: TOKEN=proof-env-secret
+    through aegis proxy:    AEGIS DENIED: read_text_file
+                            Reason: path matches deny rule '.env'
+                            Rule: deny_paths
+
+## What it does
+
+Sits between your AI coding agent and your machine:
+
+- **Deny by default** on every tool call
+- **Kernel sandbox** on subprocesses — `cat .env` can't bypass it
+- **Tamper-evident audit log** — hash-chained, integrity checked by `aegis doctor`, and checkpointed
+  from outside the sandbox under a key the sandbox can't read or write
+- **Outbound requests checked** before they're made
+- **Secrets never reach the MCP server**
+
+## Install (macOS Apple Silicon)
+
+New here? [docs/getting-started.md](docs/getting-started.md) is the step-by-step path, including the two questions that default to No.
+
+    python3 -m pip install aegis-sandbox
+    aegis init      # detects Claude Code / Cursor, asks a few questions
+    aegis doctor    # proves the boundary is actually in place
+
+**Upgrading?** Re-run `aegis init`. Your `policy.json` is yours and is never rewritten behind your back, so a
+new sandbox domain does not appear on its own — and without the OAuth token endpoint a sandboxed client stops
+working when its token expires. `aegis init` offers the new hosts; accepting is one keystroke.
+
+Prefer an app? [Download the .dmg](https://github.com/Adarsh14734/Aegis/releases/download/v0.6.0/Aegis_0.6.0_aarch64.dmg)
+
+`SHA256: bcccaa957fd3a0a15413eb1207a012f0328e309d078e7b7f2af853915e64c6dc`
+
+Unsigned build — right-click the app → Open the first time (macOS will warn about an unidentified developer, that's expected). Or build from source.
+
+## What it does NOT do
+
+- Does not stop prompt injection
+- Kernel escape defeats the sandbox
+- The audit database is still writable from inside the sandbox. Checkpoints make tampering with
+  *already-checkpointed* history detectable — not impossible, and the newest rows aren't covered yet
+- A sandboxed client can't renew an expired login token — run it once outside the sandbox to refresh
+- The sandbox can still *read* your OAuth token from the Keychain
+- Tool results larger than 16 MiB are refused
+- No external security review, no certifications
+- Not audited by anyone but me — read the source, that's why it's MIT
+
+Full threat model: THREAT-MODEL.md
+
+## License
+
+MIT

aegis_sandbox-0.8.0/aegis/__init__.py

@@ -0,0 +1,53 @@
+"""Aegis — an MCP-layer policy proxy with a tamper-evident audit trail.
+
+Read THREAT-MODEL.md before believing anything this package claims. §7 in
+particular lists what Aegis does not protect against; `aegis doctor` prints an
+abbreviated copy of it because that is where a new user will actually read it.
+
+Nothing is imported here. `aegis.policy` pulls in the whole decision path and
+`aegis.proxy` pulls in asyncio; a CLI that only wants `aegis.clients` should
+not pay for either.
+
+ONE side effect, added deliberately: the interpreter version is checked. It is
+here because it is the only code in the package guaranteed to run before any
+other — every `aegis.*` import goes through this file — and because the
+alternative was what a user actually saw:
+
+    File ".../aegis/cli.py", line 401, in <module>
+      def main(argv: list[str] | None = None) -> int:
+    TypeError: unsupported operand type(s) for |: 'types.GenericAlias' and
+    'NoneType'
+
+`list[str] | None` is valid syntax on 3.9 and a TypeError the instant the `def`
+is evaluated, so an old interpreter fails at import with a traceback about an
+annotation. That traceback tells a person nothing they can act on, and it
+arrives on screens whose whole job is to be readable. requires-python in
+pyproject.toml has said >=3.10 since the beginning; this makes the package say
+it in a sentence when something runs it anyway.
+
+Written without f-strings or annotations on purpose: it has to run on the
+interpreters it is refusing.
+"""
+
+import sys
+
+__version__ = "0.8.0"
+
+# Kept in agreement, by hand, with `requires-python` in pyproject.toml and with
+# MIN_PYTHON in aegis/verify.py — which cannot import this, by design (S0 open
+# question #4), and with MIN_PYTHON in ui/src-tauri/src/python.rs, which is a
+# different language. tests/bundle.py asserts all four agree.
+MIN_PYTHON = (3, 10)
+
+if sys.version_info < MIN_PYTHON:
+    _need = ".".join(str(n) for n in MIN_PYTHON)
+    _have = ".".join(str(n) for n in sys.version_info[:3])
+    sys.stderr.write(
+        "Aegis needs Python %s or newer, and this is Python %s.\n"
+        "  interpreter: %s\n"
+        "Nothing was read and nothing was changed.\n"
+        "Install Python %s or newer and run Aegis with it. If you have one\n"
+        "already, set AEGIS_PYTHON to its full path.\n"
+        % (_need, _have, sys.executable, _need)
+    )
+    raise SystemExit(2)

aegis_sandbox-0.8.0/aegis/approval.py

@@ -0,0 +1,219 @@
+"""Aegis S5 human approval — control C7.
+
+ASK stops collapsing to DENY. The proxy blocks the call and asks a human.
+
+**The prompt goes to the controlling terminal, /dev/tty — never to stdin or
+stdout.** stdout is the JSON-RPC channel to the client; a single stray byte
+there corrupts the protocol. stdin carries client frames. Both are already
+spoken for, and neither is a human. /dev/tty is the process's controlling
+terminal regardless of how stdin and stdout have been redirected, which is
+exactly the property needed here.
+
+Every path that is not an explicit human "yes" is a denial:
+
+  - no controlling terminal        -> DENY, rule_id ask_no_tty
+  - timeout (default 120s)         -> DENY, rule_id approval_timeout
+  - EOF, empty line, anything not affirmative -> DENY, rule_id approval_denied
+  - any error reading or writing the terminal -> DENY, rule_id ask_no_tty
+
+There is deliberately no configuration that turns an unanswered prompt into an
+approval. T5 in THREAT-MODEL.md is approval fatigue: a control that a tired
+human bypasses is not a control, and a control that approves *itself* when
+nobody answers is worse than not having asked.
+"""
+
+import getpass
+import os
+import select
+import socket
+import sys
+import time
+from dataclasses import dataclass
+
+TTY_PATH = "/dev/tty"
+DEFAULT_TIMEOUT_SECONDS = 120.0
+
+AFFIRMATIVE = {"y", "yes"}
+
+
+@dataclass(frozen=True)
+class Resolution:
+    approved: bool
+    rule_id: str
+    resolver: str
+    detail: str
+
+
+def _who(tty_name: str) -> str:
+    """Who answered. Best effort — this is provenance for the audit trail, not
+    authentication. Anyone who can write to the terminal can answer the
+    prompt, and Aegis cannot tell one such person from another."""
+    try:
+        user = getpass.getuser()
+    except Exception:  # noqa: BLE001 - no account name is not worth failing over
+        user = "?"
+    try:
+        host = socket.gethostname()
+    except Exception:  # noqa: BLE001
+        host = "?"
+    return f"{user}@{host} via {tty_name}"
+
+
+def describe(tool: str, rule_id: str, reason: str, paths) -> str:
+    """The prompt a human actually reads. Plain English, no jargon, and the
+    consequence of doing nothing stated explicitly."""
+    lines = [
+        "",
+        "=" * 66,
+        "  AEGIS — approval required",
+        "=" * 66,
+        f"  Tool:  {tool}",
+    ]
+    paths = list(paths)
+    if paths:
+        lines.append(f"  Files: {paths[0]}")
+        for p in paths[1:6]:
+            lines.append(f"         {p}")
+        if len(paths) > 6:
+            lines.append(f"         ...and {len(paths) - 6} more ({len(paths)} total)")
+    else:
+        lines.append("  Files: (none named in this call)")
+    lines += [
+        f"  Why:   {reason}",
+        f"  Rule:  {rule_id}",
+        "",
+        "  Approving lets this call through to the server. Denying stops it.",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def prompt_on(stream, tool: str, rule_id: str, reason: str, paths,
+              timeout: float = DEFAULT_TIMEOUT_SECONDS) -> Resolution:
+    """Ask on an already-open terminal stream. Split out from resolve() so the
+    prompt, the timeout and the parsing can be tested against a real pty
+    without needing a controlling terminal."""
+    tty_name = getattr(stream, "name", TTY_PATH)
+    try:
+        tty_name = os.ttyname(stream.fileno())
+    except (OSError, ValueError, AttributeError):
+        pass
+
+    try:
+        stream.write(describe(tool, rule_id, reason, paths).encode("utf-8"))
+        stream.write(
+            f"  Denied automatically in {int(timeout)}s if nobody answers.\n"
+            f"  Approve? [y/N] ".encode("utf-8")
+        )
+    except (OSError, ValueError) as exc:
+        return Resolution(False, "ask_no_tty", "none",
+                          f"could not write the prompt to {tty_name}: {exc}")
+
+    deadline = time.monotonic() + timeout
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            _say(stream, "\n  TIMED OUT — denied.\n")
+            return Resolution(False, "approval_timeout", "timeout",
+                              f"nobody answered within {int(timeout)}s")
+        try:
+            readable, _, _ = select.select([stream], [], [], min(remaining, 1.0))
+        except (OSError, ValueError) as exc:
+            return Resolution(False, "ask_no_tty", "none",
+                              f"terminal became unreadable: {exc}")
+        if not readable:
+            continue
+
+        try:
+            line = stream.readline()
+        except (OSError, ValueError) as exc:
+            return Resolution(False, "ask_no_tty", "none",
+                              f"could not read the answer: {exc}")
+
+        if not line:  # EOF — the terminal went away
+            return Resolution(False, "approval_denied", "eof",
+                              "the terminal closed without an answer")
+
+        answer = line.decode("utf-8", errors="replace").strip().lower()
+        who = _who(tty_name)
+        if answer in AFFIRMATIVE:
+            _say(stream, "  APPROVED.\n")
+            return Resolution(True, "approval_granted", who, "answered yes")
+        _say(stream, "  DENIED.\n")
+        return Resolution(
+            False, "approval_denied", who,
+            f"answered {answer!r}" if answer else "answered with an empty line",
+        )
+
+
+def _say(stream, text: str) -> None:
+    try:
+        stream.write(text.encode("utf-8"))
+    except (OSError, ValueError):
+        pass
+
+
+def controlling_tty_available(tty_path: str = TTY_PATH) -> tuple[bool, str]:
+    """Is there a controlling terminal to prompt on? (available, why not).
+
+    Checked *before* anything is written, so the headless case is answered
+    immediately instead of after the timeout. O_NOCTTY because probing for a
+    terminal must never have the side effect of acquiring one.
+    """
+    try:
+        fd = os.open(tty_path, os.O_RDWR | os.O_NOCTTY)
+    except OSError as exc:
+        return False, f"{tty_path}: {exc.strerror}"
+    try:
+        if not os.isatty(fd):
+            return False, f"{tty_path} is not a terminal"
+    finally:
+        os.close(fd)
+    return True, ""
+
+
+def resolve(tool: str, rule_id: str, reason: str, paths,
+            timeout: float = DEFAULT_TIMEOUT_SECONDS,
+            tty_path: str = TTY_PATH) -> Resolution:
+    """Open the controlling terminal and ask. Blocking; the proxy runs this in
+    an executor so the server->client pump keeps flowing while a human thinks.
+
+    No controlling terminal means DENY, **immediately**. That is the headless
+    case — a proxy launched by a GUI client, a daemon, CI — and it must never
+    silently become an approval.
+
+    The absence is detected before prompting rather than discovered by nobody
+    answering. Two reasons, and the second is the one that matters:
+
+      - waiting out a 120s timeout on every ASK makes headless operation look
+        like a hang, once per call;
+      - "nobody was present to ask" and "a human was asked and did not answer"
+        are different events. Recording both as approval_timeout would put a
+        claim in the audit trail — that a person saw this and let it lapse —
+        which is not true. They get different rule_ids because they are
+        different facts.
+    """
+    available, why = controlling_tty_available(tty_path)
+    if not available:
+        return Resolution(
+            False, "ask_no_tty", "none",
+            f"no controlling terminal ({why}), so no human could be asked; "
+            f"denied immediately without waiting {int(timeout)}s, and recorded "
+            f"as nobody-present rather than as an unanswered prompt",
+        )
+
+    try:
+        stream = open(tty_path, "r+b", buffering=0)
+    except OSError as exc:
+        # Raced between the probe and the open — still nobody to ask.
+        return Resolution(
+            False, "ask_no_tty", "none",
+            f"controlling terminal disappeared ({tty_path}: {exc.strerror}); "
+            f"denying rather than assuming consent",
+        )
+    try:
+        return prompt_on(stream, tool, rule_id, reason, paths, timeout)
+    finally:
+        try:
+            stream.close()
+        except OSError:
+            pass