@agenshield/patcher 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,109 @@
+# @agenshield/patcher
+
+Python network isolation via `sitecustomize.py` patching and optional macOS seatbelt wrappers. This package installs a Python runtime patch that blocks direct network access and routes selected HTTP traffic through the AgenShield broker.
+
+## Purpose
+- Prevent direct outbound network calls from Python code.
+- Route `requests` traffic through the broker HTTP fallback.
+- Optionally wrap Python with `sandbox-exec` on macOS.
+
+## Key Components
+- `src/install.ts` - `PythonPatcher` (install/uninstall/isInstalled).
+- `src/verify.ts` - `PythonVerifier` to validate the patch.
+- `src/python/sitecustomize.ts` - Generates patched `sitecustomize.py`.
+- `src/python/wrapper.ts` - Generates a wrapper shell script.
+- `src/python/sandbox-profile.ts` - Generates a macOS seatbelt profile.
+
+## Usage
+### Install
+```ts
+import { PythonPatcher } from '@agenshield/patcher';
+
+const patcher = new PythonPatcher({
+  pythonPath: '/usr/bin/python3',
+  brokerHost: 'localhost',
+  brokerPort: 5200,
+  useSandbox: true,
+  workspacePath: '/Users/clawagent/workspace',
+  socketPath: '/var/run/agenshield.sock',
+  installDir: '/Users/clawagent/bin'
+});
+
+const result = await patcher.install();
+```
+
+### Verify
+```ts
+import { PythonVerifier } from '@agenshield/patcher';
+
+const verifier = new PythonVerifier({ pythonPath: '/usr/bin/python3' });
+const report = await verifier.verify();
+```
+
+### Generate Assets
+```ts
+import { generateSitecustomize, generatePythonWrapper, generateSandboxProfile } from '@agenshield/patcher';
+
+const sitecustomize = generateSitecustomize({
+  brokerHost: 'localhost',
+  brokerPort: 5200,
+  logLevel: 'warn',
+  enabled: true,
+});
+
+const wrapper = generatePythonWrapper({
+  pythonPath: '/usr/bin/python3',
+  sitecustomizePath: '/path/to/sitecustomize.py',
+  useSandbox: true,
+  sandboxProfilePath: '/etc/agenshield/seatbelt/python.sb',
+});
+
+const profile = generateSandboxProfile({
+  workspacePath: '/Users/clawagent/workspace',
+  pythonPath: '/usr/bin/python3',
+  brokerHost: 'localhost',
+  brokerPort: 5200,
+});
+```
+
+## How the Patch Works
+- `socket.connect` and `socket.create_connection` are overridden to allow only broker connections.
+- `requests.Session.request` is patched to proxy HTTP requests through the broker (`/rpc`).
+- `urllib3` is patched to *block* non-broker connections (it does not proxy).
+- `aiohttp` is patched to *block* non-broker connections.
+
+## Environment Variables (sitecustomize)
+- `AGENSHIELD_ENABLED` - `true`/`false` to toggle patching.
+- `AGENSHIELD_BROKER_HOST` - Broker HTTP host.
+- `AGENSHIELD_BROKER_PORT` - Broker HTTP port.
+- `AGENSHIELD_LOG_LEVEL` - `debug|info|warn|error`.
+
+## Limitations and Caveats
+- Installs `sitecustomize.py` into the *system* site-packages; requires permissions.
+- Virtual environments are not explicitly supported; `getsitepackages()[0]` may not be the active venv.
+- Only `requests` is proxied through the broker; `urllib3` and `aiohttp` are blocked rather than proxied.
+- macOS-only sandboxing (`sandbox-exec`) is used when `useSandbox` is true.
+- Wrapper scripts do not remove seatbelt profiles on uninstall.
+- The wrapper sets `PYTHONPATH` to a file path; site-packages installation is the primary mechanism.
+
+## Roadmap (Ideas)
+- Venv-aware installation and uninstall.
+- Proxy support for `urllib3` and `aiohttp`.
+- Cross-platform sandboxing alternatives.
+- Cleaner wrapper env handling and profile lifecycle management.
+
+## Development
+```bash
+# Build
+npx nx build shield-patcher
+```
+
+## Contribution Guide
+- Keep generated Python output minimal and deterministic.
+- Any changes to `sitecustomize.py` should include a verifier update.
+- Ensure new patches fail closed by default.
+
+## Agent Notes
+- `PythonPatcher.install()` writes to site-packages and optionally creates a wrapper and seatbelt profile.
+- `PythonVerifier.verify()` uses real network probes; keep timeouts reasonable.
+- `generateSandboxProfile()` emits a restrictive policy; any new paths should be explicit.

package/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @agenshield/patcher
+ *
+ * Python network isolation via sitecustomize.py patching.
+ */
+export { PythonPatcher } from './install.js';
+export { PythonVerifier, verifyPython } from './verify.js';
+export { generateSitecustomize, generatePythonWrapper, generateSandboxProfile, } from './python/index.js';
+export type { PatcherConfig, PatcherResult, VerificationResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,aAAa,EACb,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/index.js

@@ -0,0 +1,633 @@
+// libs/shield-patcher/src/install.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+// libs/shield-patcher/src/python/sitecustomize.ts
+function generateSitecustomize(config) {
+  return `# -*- coding: utf-8 -*-
+"""
+AgenShield Python Network Isolation
+
+This module patches Python's networking to route all traffic through
+the AgenShield broker daemon.
+
+Generated by @agenshield/patcher
+"""
+
+import os
+import sys
+import socket
+import functools
+
+# Configuration
+_AGENSHIELD_ENABLED = ${config.enabled ? "True" : "False"}
+_AGENSHIELD_BROKER_HOST = '${config.brokerHost}'
+_AGENSHIELD_BROKER_PORT = ${config.brokerPort}
+_AGENSHIELD_LOG_LEVEL = '${config.logLevel}'
+
+# Override from environment
+if os.environ.get('AGENSHIELD_ENABLED') == 'false':
+    _AGENSHIELD_ENABLED = False
+if os.environ.get('AGENSHIELD_BROKER_HOST'):
+    _AGENSHIELD_BROKER_HOST = os.environ['AGENSHIELD_BROKER_HOST']
+if os.environ.get('AGENSHIELD_BROKER_PORT'):
+    _AGENSHIELD_BROKER_PORT = int(os.environ['AGENSHIELD_BROKER_PORT'])
+if os.environ.get('AGENSHIELD_LOG_LEVEL'):
+    _AGENSHIELD_LOG_LEVEL = os.environ['AGENSHIELD_LOG_LEVEL']
+
+# Logging
+def _agenshield_log(level, message):
+    levels = {'debug': 0, 'info': 1, 'warn': 2, 'error': 3}
+    if levels.get(level, 0) >= levels.get(_AGENSHIELD_LOG_LEVEL, 1):
+        print(f'[AgenShield] {level.upper()}: {message}', file=sys.stderr)
+
+# Mark as patched
+_agenshield_patched = True
+
+if _AGENSHIELD_ENABLED:
+    _agenshield_log('info', 'Network isolation enabled')
+
+    # ========================================
+    # Socket Patching
+    # ========================================
+
+    _original_socket_connect = socket.socket.connect
+    _original_create_connection = socket.create_connection
+
+    def _agenshield_is_allowed(host, port):
+        """Check if connection to host:port is allowed."""
+        # Always allow localhost broker
+        if host in ('localhost', '127.0.0.1', '::1') and port == _AGENSHIELD_BROKER_PORT:
+            return True
+        # Block everything else
+        return False
+
+    def _agenshield_socket_connect(self, address):
+        """Patched socket.connect that blocks non-localhost connections."""
+        try:
+            host, port = address[:2]
+        except (TypeError, ValueError):
+            # Unix socket or other format
+            return _original_socket_connect(self, address)
+
+        if not _agenshield_is_allowed(host, port):
+            _agenshield_log('warn', f'Blocked connection to {host}:{port}')
+            raise ConnectionRefusedError(
+                f'AgenShield: Direct connections blocked. '
+                f'Use broker at {_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}'
+            )
+
+        return _original_socket_connect(self, address)
+
+    def _agenshield_create_connection(address, timeout=socket._GLOBAL_DEFAULT_TIMEOUT,
+                                       source_address=None, *, all_errors=False):
+        """Patched socket.create_connection."""
+        host, port = address
+
+        if not _agenshield_is_allowed(host, port):
+            _agenshield_log('warn', f'Blocked create_connection to {host}:{port}')
+            raise ConnectionRefusedError(
+                f'AgenShield: Direct connections blocked. '
+                f'Use broker at {_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}'
+            )
+
+        return _original_create_connection(address, timeout, source_address,
+                                            all_errors=all_errors)
+
+    # Apply socket patches
+    socket.socket.connect = _agenshield_socket_connect
+    socket.create_connection = _agenshield_create_connection
+
+    # ========================================
+    # urllib3 Patching (if available)
+    # ========================================
+
+    try:
+        import urllib3.connection
+        import urllib3.util.connection
+
+        _original_urllib3_create_connection = urllib3.util.connection.create_connection
+
+        def _agenshield_urllib3_create_connection(address, timeout=socket._GLOBAL_DEFAULT_TIMEOUT,
+                                                   source_address=None, socket_options=None):
+            """Patched urllib3 create_connection."""
+            host, port = address
+
+            if not _agenshield_is_allowed(host, port):
+                _agenshield_log('warn', f'Blocked urllib3 connection to {host}:{port}')
+                raise ConnectionRefusedError(
+                    f'AgenShield: Direct connections blocked. '
+                    f'Use broker at {_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}'
+                )
+
+            return _original_urllib3_create_connection(address, timeout, source_address,
+                                                        socket_options)
+
+        urllib3.util.connection.create_connection = _agenshield_urllib3_create_connection
+        _agenshield_log('debug', 'Patched urllib3')
+
+    except ImportError:
+        _agenshield_log('debug', 'urllib3 not available, skipping patch')
+
+    # ========================================
+    # requests Patching (if available)
+    # ========================================
+
+    try:
+        import requests
+        import json
+
+        _original_requests_request = requests.Session.request
+
+        def _agenshield_requests_request(self, method, url, **kwargs):
+            """Patched requests.Session.request that routes through broker."""
+            from urllib.parse import urlparse
+
+            parsed = urlparse(url)
+
+            # Allow broker connections
+            if parsed.netloc == f'{_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}':
+                return _original_requests_request(self, method, url, **kwargs)
+
+            _agenshield_log('info', f'Routing {method} {url} through broker')
+
+            # Route through broker
+            broker_url = f'http://{_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}/rpc'
+
+            # Prepare broker request
+            headers = dict(kwargs.get('headers', {}))
+            body = kwargs.get('data') or kwargs.get('json')
+            if isinstance(body, dict):
+                body = json.dumps(body)
+
+            broker_request = {
+                'jsonrpc': '2.0',
+                'id': '1',
+                'method': 'http_request',
+                'params': {
+                    'url': url,
+                    'method': method.upper(),
+                    'headers': headers,
+                    'body': body,
+                }
+            }
+
+            # Make broker request
+            response = _original_requests_request(
+                self, 'POST', broker_url,
+                json=broker_request,
+                timeout=kwargs.get('timeout', 30)
+            )
+
+            # Parse broker response
+            broker_response = response.json()
+
+            if 'error' in broker_response:
+                raise requests.exceptions.RequestException(
+                    f"AgenShield: {broker_response['error']['message']}"
+                )
+
+            result = broker_response['result']
+
+            # Create fake response
+            fake_response = requests.models.Response()
+            fake_response.status_code = result['status']
+            fake_response._content = result['body'].encode('utf-8')
+            fake_response.headers = requests.structures.CaseInsensitiveDict(result['headers'])
+            fake_response.url = url
+            fake_response.request = None
+
+            return fake_response
+
+        requests.Session.request = _agenshield_requests_request
+        _agenshield_log('debug', 'Patched requests')
+
+    except ImportError:
+        _agenshield_log('debug', 'requests not available, skipping patch')
+
+    # ========================================
+    # aiohttp Patching (if available)
+    # ========================================
+
+    try:
+        import aiohttp
+
+        _original_aiohttp_request = aiohttp.ClientSession._request
+
+        async def _agenshield_aiohttp_request(self, method, url, **kwargs):
+            """Patched aiohttp request."""
+            from urllib.parse import urlparse
+
+            parsed = urlparse(str(url))
+
+            # Allow broker connections
+            if parsed.netloc == f'{_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}':
+                return await _original_aiohttp_request(self, method, url, **kwargs)
+
+            _agenshield_log('warn', f'Blocked aiohttp request to {url}')
+            raise aiohttp.ClientError(
+                f'AgenShield: Direct connections blocked. '
+                f'Use broker at {_AGENSHIELD_BROKER_HOST}:{_AGENSHIELD_BROKER_PORT}'
+            )
+
+        aiohttp.ClientSession._request = _agenshield_aiohttp_request
+        _agenshield_log('debug', 'Patched aiohttp')
+
+    except ImportError:
+        _agenshield_log('debug', 'aiohttp not available, skipping patch')
+
+    _agenshield_log('info', 'Network isolation patches applied')
+
+else:
+    _agenshield_log('info', 'Network isolation disabled')
+`;
+}
+
+// libs/shield-patcher/src/python/wrapper.ts
+function generatePythonWrapper(config) {
+  const envVars = Object.entries(config.environmentVariables || {}).map(([key, value]) => `export ${key}="${value}"`).join("\n");
+  if (config.useSandbox && config.sandboxProfilePath) {
+    return `#!/bin/bash
+# AgenShield Python Wrapper
+# Generated by @agenshield/patcher
+
+set -e
+
+# Environment setup
+export PYTHONDONTWRITEBYTECODE=1
+${envVars}
+
+# Run Python under sandbox-exec
+exec /usr/bin/sandbox-exec -f "${config.sandboxProfilePath}" \\
+    "${config.pythonPath}" "$@"
+`;
+  }
+  return `#!/bin/bash
+# AgenShield Python Wrapper
+# Generated by @agenshield/patcher
+
+set -e
+
+# Environment setup
+export PYTHONDONTWRITEBYTECODE=1
+${envVars}
+
+# Ensure sitecustomize is loaded
+export PYTHONPATH="${config.sitecustomizePath}:\${PYTHONPATH:-}"
+
+# Run Python
+exec "${config.pythonPath}" "$@"
+`;
+}
+
+// libs/shield-patcher/src/python/sandbox-profile.ts
+function generateSandboxProfile(config) {
+  const additionalReadPaths = (config.additionalReadPaths || []).map((p) => `(allow file-read* (subpath "${p}"))`).join("\n");
+  const additionalWritePaths = (config.additionalWritePaths || []).map((p) => `(allow file-write* (subpath "${p}"))`).join("\n");
+  return `;;
+;; AgenShield Python Sandbox Profile
+;; Generated by @agenshield/patcher
+;;
+
+(version 1)
+(deny default)
+
+;; ========================================
+;; System Libraries & Frameworks
+;; ========================================
+(allow file-read*
+  (subpath "/System")
+  (subpath "/usr/lib")
+  (subpath "/usr/share")
+  (subpath "/Library/Frameworks")
+  (subpath "/private/var/db")
+  (subpath "/private/etc"))
+
+;; ========================================
+;; Python Installation
+;; ========================================
+(allow file-read*
+  (subpath "${config.pythonPath}")
+  (subpath "/Library/Frameworks/Python.framework")
+  (subpath "/usr/local/lib/python")
+  (subpath "/opt/homebrew/lib/python")
+  (subpath "/usr/local/Cellar/python"))
+
+;; Python needs to read its own files
+(allow file-read*
+  (regex #".*\\.py$")
+  (regex #".*\\.pyc$")
+  (regex #".*\\.pyo$")
+  (regex #".*\\.so$")
+  (regex #".*\\.dylib$"))
+
+;; ========================================
+;; Workspace Access (Read/Write)
+;; ========================================
+(allow file-read* file-write*
+  (subpath "${config.workspacePath}"))
+
+;; Temp directories
+(allow file-read* file-write*
+  (subpath "/tmp")
+  (subpath "/private/tmp")
+  (subpath "/var/folders"))
+
+;; ========================================
+;; Additional Paths
+;; ========================================
+${additionalReadPaths}
+${additionalWritePaths}
+
+;; ========================================
+;; Network (RESTRICTED)
+;; ========================================
+
+;; Block all network by default
+(deny network*)
+
+;; Allow ONLY broker connection
+(allow network-outbound
+  (remote tcp "${config.brokerHost}:${config.brokerPort}"))
+
+;; Allow localhost loopback for broker
+(allow network-outbound
+  (remote tcp "localhost:${config.brokerPort}")
+  (remote tcp "127.0.0.1:${config.brokerPort}"))
+
+;; ========================================
+;; Process & Signal
+;; ========================================
+(allow process-fork)
+(allow process-exec
+  (literal "${config.pythonPath}")
+  (literal "/usr/bin/env")
+  (literal "/bin/sh")
+  (subpath "/usr/local/bin"))
+
+(allow signal (target self))
+(allow sysctl-read)
+
+;; ========================================
+;; Mach IPC (Limited)
+;; ========================================
+(allow mach-lookup
+  (global-name "com.apple.system.opendirectoryd.libinfo")
+  (global-name "com.apple.system.notification_center")
+  (global-name "com.apple.CoreServices.coreservicesd")
+  (global-name "com.apple.SecurityServer"))
+
+;; ========================================
+;; User Defaults (Read-only)
+;; ========================================
+(allow user-preference-read)
+`;
+}
+
+// libs/shield-patcher/src/install.ts
+var execAsync = promisify(exec);
+var PythonPatcher = class {
+  config;
+  constructor(config) {
+    this.config = {
+      pythonPath: config.pythonPath,
+      brokerHost: config.brokerHost || "localhost",
+      brokerPort: config.brokerPort || 5200,
+      useSandbox: config.useSandbox ?? true,
+      workspacePath: config.workspacePath || "/Users/clawagent/workspace",
+      socketPath: config.socketPath || "/var/run/agenshield/agenshield.sock",
+      installDir: config.installDir
+    };
+  }
+  /**
+   * Install the Python patcher
+   */
+  async install() {
+    try {
+      const sitePackages = await this.getSitePackagesDir();
+      const sitecustomizePath = path.join(sitePackages, "sitecustomize.py");
+      const sitecustomizeContent = generateSitecustomize({
+        brokerHost: this.config.brokerHost,
+        brokerPort: this.config.brokerPort,
+        logLevel: "warn",
+        enabled: true
+      });
+      await fs.writeFile(sitecustomizePath, sitecustomizeContent, {
+        mode: 420
+      });
+      const result = {
+        success: true,
+        message: "Python patcher installed successfully",
+        paths: {
+          sitecustomize: sitecustomizePath
+        }
+      };
+      if (this.config.installDir) {
+        const wrapperPath = path.join(this.config.installDir, "python");
+        const wrapperContent = generatePythonWrapper({
+          pythonPath: this.config.pythonPath,
+          sitecustomizePath,
+          useSandbox: this.config.useSandbox,
+          sandboxProfilePath: this.config.useSandbox ? "/etc/agenshield/seatbelt/python.sb" : void 0
+        });
+        await fs.writeFile(wrapperPath, wrapperContent, { mode: 493 });
+        result.paths.wrapper = wrapperPath;
+        if (this.config.useSandbox) {
+          const profilePath = "/etc/agenshield/seatbelt/python.sb";
+          const profileDir = path.dirname(profilePath);
+          await fs.mkdir(profileDir, { recursive: true });
+          const profileContent = generateSandboxProfile({
+            workspacePath: this.config.workspacePath,
+            pythonPath: this.config.pythonPath,
+            brokerHost: this.config.brokerHost,
+            brokerPort: this.config.brokerPort
+          });
+          await fs.writeFile(profilePath, profileContent, { mode: 420 });
+          result.paths.sandboxProfile = profilePath;
+        }
+      }
+      return result;
+    } catch (error) {
+      return {
+        success: false,
+        message: `Installation failed: ${error.message}`,
+        error
+      };
+    }
+  }
+  /**
+   * Uninstall the Python patcher
+   */
+  async uninstall() {
+    try {
+      const sitePackages = await this.getSitePackagesDir();
+      const sitecustomizePath = path.join(sitePackages, "sitecustomize.py");
+      try {
+        const content = await fs.readFile(sitecustomizePath, "utf-8");
+        if (!content.includes("AgenShield")) {
+          return {
+            success: false,
+            message: "sitecustomize.py does not appear to be AgenShield installation"
+          };
+        }
+        await fs.unlink(sitecustomizePath);
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      if (this.config.installDir) {
+        const wrapperPath = path.join(this.config.installDir, "python");
+        try {
+          await fs.unlink(wrapperPath);
+        } catch {
+        }
+      }
+      return {
+        success: true,
+        message: "Python patcher uninstalled successfully"
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Uninstallation failed: ${error.message}`,
+        error
+      };
+    }
+  }
+  /**
+   * Check if patcher is installed
+   */
+  async isInstalled() {
+    try {
+      const sitePackages = await this.getSitePackagesDir();
+      const sitecustomizePath = path.join(sitePackages, "sitecustomize.py");
+      const content = await fs.readFile(sitecustomizePath, "utf-8");
+      return content.includes("AgenShield");
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get Python version
+   */
+  async getPythonVersion() {
+    const { stdout } = await execAsync(`${this.config.pythonPath} --version`);
+    return stdout.trim();
+  }
+  /**
+   * Get site-packages directory
+   */
+  async getSitePackagesDir() {
+    const { stdout } = await execAsync(
+      `${this.config.pythonPath} -c "import site; print(site.getsitepackages()[0])"`
+    );
+    return stdout.trim();
+  }
+};
+
+// libs/shield-patcher/src/verify.ts
+import { exec as exec2 } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+var execAsync2 = promisify2(exec2);
+var PythonVerifier = class {
+  pythonPath;
+  brokerHost;
+  brokerPort;
+  constructor(options) {
+    this.pythonPath = options.pythonPath;
+    this.brokerHost = options.brokerHost || "localhost";
+    this.brokerPort = options.brokerPort || 5200;
+  }
+  /**
+   * Verify the Python patcher installation
+   */
+  async verify() {
+    const details = [];
+    let success = true;
+    let pythonVersion = "unknown";
+    try {
+      const { stdout } = await execAsync2(`${this.pythonPath} --version`);
+      pythonVersion = stdout.trim();
+      details.push(`Python version: ${pythonVersion}`);
+    } catch (error) {
+      details.push(`Failed to get Python version: ${error.message}`);
+      success = false;
+    }
+    let sitecustomizeInstalled = false;
+    try {
+      const { stdout } = await execAsync2(
+        `${this.pythonPath} -c "import sitecustomize; print('AgenShield' in dir(sitecustomize) or hasattr(sitecustomize, '_agenshield_patched'))"`
+      );
+      sitecustomizeInstalled = stdout.trim() === "True";
+      details.push(
+        sitecustomizeInstalled ? "sitecustomize.py: AgenShield patch found" : "sitecustomize.py: AgenShield patch NOT found"
+      );
+    } catch {
+      details.push("sitecustomize.py: Not installed or error loading");
+    }
+    let networkBlocked = false;
+    try {
+      const { stderr } = await execAsync2(
+        `${this.pythonPath} -c "import socket; socket.create_connection(('example.com', 80), timeout=5)" 2>&1`,
+        { timeout: 1e4 }
+      );
+      details.push("Network blocking: DISABLED (direct connections allowed)");
+    } catch (error) {
+      const message = error.message;
+      if (message.includes("AgenShield") || message.includes("Connection refused") || message.includes("blocked")) {
+        networkBlocked = true;
+        details.push("Network blocking: ENABLED");
+      } else {
+        details.push(`Network blocking: Unknown (${message})`);
+      }
+    }
+    let brokerAccessible = false;
+    try {
+      const script = `
+import urllib.request
+import json
+
+req = urllib.request.Request(
+    'http://${this.brokerHost}:${this.brokerPort}/health',
+    method='GET'
+)
+with urllib.request.urlopen(req, timeout=5) as response:
+    data = json.loads(response.read())
+    print('ok' if data.get('status') == 'ok' else 'error')
+`;
+      const { stdout } = await execAsync2(`${this.pythonPath} -c "${script}"`, {
+        timeout: 1e4
+      });
+      brokerAccessible = stdout.trim() === "ok";
+      details.push(
+        brokerAccessible ? "Broker: Accessible" : "Broker: Not accessible (check if running)"
+      );
+    } catch {
+      details.push("Broker: Not accessible");
+    }
+    success = sitecustomizeInstalled && networkBlocked && brokerAccessible;
+    return {
+      success,
+      pythonVersion,
+      sitecustomizeInstalled,
+      networkBlocked,
+      brokerAccessible,
+      details
+    };
+  }
+};
+async function verifyPython(pythonPath) {
+  const verifier = new PythonVerifier({ pythonPath });
+  return verifier.verify();
+}
+export {
+  PythonPatcher,
+  PythonVerifier,
+  generatePythonWrapper,
+  generateSandboxProfile,
+  generateSitecustomize,
+  verifyPython
+};

package/install.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Python Patcher Installation
+ */
+import type { PatcherConfig, PatcherResult } from './types.js';
+export declare class PythonPatcher {
+    private config;
+    constructor(config: Partial<PatcherConfig> & {
+        pythonPath: string;
+    });
+    /**
+     * Install the Python patcher
+     */
+    install(): Promise<PatcherResult>;
+    /**
+     * Uninstall the Python patcher
+     */
+    uninstall(): Promise<PatcherResult>;
+    /**
+     * Check if patcher is installed
+     */
+    isInstalled(): Promise<boolean>;
+    /**
+     * Get Python version
+     */
+    getPythonVersion(): Promise<string>;
+    /**
+     * Get site-packages directory
+     */
+    private getSitePackagesDir;
+}
+//# sourceMappingURL=install.d.ts.map

package/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAS/D,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAYnE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAsEvC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC;IA6CzC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAYrC;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKzC;;OAEG;YACW,kBAAkB;CAMjC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@agenshield/patcher",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Python network isolation via sitecustomize.py patching",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@agenshield/ipc": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/python/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python file generators
+ */
+export { generateSitecustomize } from './sitecustomize.js';
+export { generatePythonWrapper } from './wrapper.js';
+export { generateSandboxProfile } from './sandbox-profile.js';
+//# sourceMappingURL=index.d.ts.map

package/python/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/python/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}

package/python/sandbox-profile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * macOS Sandbox Profile Generator for Python
+ */
+import type { SandboxProfileConfig } from '../types.js';
+export declare function generateSandboxProfile(config: SandboxProfileConfig): string;
+//# sourceMappingURL=sandbox-profile.d.ts.map

package/python/sandbox-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-profile.d.ts","sourceRoot":"","sources":["../../src/python/sandbox-profile.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA2G3E"}

package/python/sitecustomize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * sitecustomize.py Generator
+ */
+import type { SitecustomizeConfig } from '../types.js';
+export declare function generateSitecustomize(config: SitecustomizeConfig): string;
+//# sourceMappingURL=sitecustomize.d.ts.map

package/python/sitecustomize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitecustomize.d.ts","sourceRoot":"","sources":["../../src/python/sitecustomize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CA8OzE"}

package/python/wrapper.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Python Wrapper Script Generator
+ */
+import type { WrapperConfig } from '../types.js';
+export declare function generatePythonWrapper(config: WrapperConfig): string;
+//# sourceMappingURL=wrapper.d.ts.map

package/python/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../src/python/wrapper.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAsCnE"}

package/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Python Patcher Types
+ */
+export interface PatcherConfig {
+    /** Path to Python executable */
+    pythonPath: string;
+    /** Broker HTTP host */
+    brokerHost: string;
+    /** Broker HTTP port */
+    brokerPort: number;
+    /** Whether to use macOS sandbox */
+    useSandbox: boolean;
+    /** Workspace directory */
+    workspacePath: string;
+    /** Broker socket path */
+    socketPath: string;
+    /** Installation target directory */
+    installDir?: string;
+}
+export interface PatcherResult {
+    success: boolean;
+    message: string;
+    paths?: {
+        sitecustomize: string;
+        wrapper?: string;
+        sandboxProfile?: string;
+    };
+    error?: Error;
+}
+export interface VerificationResult {
+    success: boolean;
+    pythonVersion: string;
+    sitecustomizeInstalled: boolean;
+    networkBlocked: boolean;
+    brokerAccessible: boolean;
+    details: string[];
+}
+export interface SitecustomizeConfig {
+    brokerHost: string;
+    brokerPort: number;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    enabled: boolean;
+}
+export interface WrapperConfig {
+    pythonPath: string;
+    sitecustomizePath: string;
+    useSandbox: boolean;
+    sandboxProfilePath?: string;
+    environmentVariables?: Record<string, string>;
+}
+export interface SandboxProfileConfig {
+    workspacePath: string;
+    pythonPath: string;
+    brokerHost: string;
+    brokerPort: number;
+    additionalReadPaths?: string[];
+    additionalWritePaths?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IAEnB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;IAEpB,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;IAEtB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,EAAE,OAAO,CAAC;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC"}

package/verify.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Python Patcher Verification
+ */
+import type { VerificationResult } from './types.js';
+export declare class PythonVerifier {
+    private pythonPath;
+    private brokerHost;
+    private brokerPort;
+    constructor(options: {
+        pythonPath: string;
+        brokerHost?: string;
+        brokerPort?: number;
+    });
+    /**
+     * Verify the Python patcher installation
+     */
+    verify(): Promise<VerificationResult>;
+}
+/**
+ * Quick verification function
+ */
+export declare function verifyPython(pythonPath: string): Promise<VerificationResult>;
+//# sourceMappingURL=verify.d.ts.map

package/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIrD,qBAAa,cAAc;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAMD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;CA8F5C;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAGlF"}