up

docs/24_OFFLINE_KIT.md

@@ -41,6 +41,48 @@ completely isolated network:
 
 The PHP analyzer parses `composer.lock` for Composer dependencies and supports optional runtime evidence via the `stella-trace.php` shim; set `STELLA_PHP_OPCACHE=1` to enable opcache statistics collection.
 
+**Python analyzer features:**
+- **Wheel/sdist/editable** parsing with dependency edges from `METADATA`, `PKG-INFO`, `requirements.txt`, and `pyproject.toml`
+- **Virtual environment** support for virtualenv, venv, and conda prefix layouts
+- **PEP 420 namespace packages** with proper `importlib` resolution semantics across `sys.path`
+- **Python version detection** via `pyproject.toml`, `runtime.txt`, Dockerfile `FROM python:*`, `.python-version`
+- **Native extension detection** for `.so`, `.pyd`, CFFI modules, ctypes loaders, and embedded WASM
+- **Framework/config heuristics** for Django, Flask, FastAPI, Celery, AWS Lambda, Gunicorn, Click/Typer CLIs
+- **AOC-compliant observations**: entrypoints (module `__main__`, console_scripts, zipapp), components (modules/packages/native), edges (import, namespace, dynamic-hint, native-extension) with resolver traces
+- **Optional runtime evidence** via import hook; the bundled `stellaops_trace.py` module captures module load events with SHA-256 path hashing for secure evidence correlation
+- **CLI inspection**: run `stella python inspect --root /path/to/app` to analyze a Python workspace locally
+
+**Surface.Env configuration:** Scanner Worker and WebService components use the Surface.Env library for configuration discovery. In air-gapped deployments, configure the following environment variables (see `docs/modules/scanner/design/surface-env.md` for details):
+
+| Variable | Description | Air-gap Default |
+|----------|-------------|-----------------|
+| `SCANNER_SURFACE_FS_ENDPOINT` | Base URI for Surface.FS / RustFS storage | `http://rustfs:8080` |
+| `SCANNER_SURFACE_FS_BUCKET` | Bucket for manifests/artefacts | `surface-cache` |
+| `SCANNER_SURFACE_CACHE_ROOT` | Local cache directory | `/var/lib/stellaops/surface` |
+| `SCANNER_SURFACE_CACHE_QUOTA_MB` | Cache quota in MB (64-262144) | `4096` |
+| `SCANNER_SURFACE_PREFETCH_ENABLED` | Enable manifest prefetch | `false` |
+| `SCANNER_SURFACE_TENANT` | Tenant namespace | `default` |
+| `SCANNER_SURFACE_SECRETS_PROVIDER` | Secrets provider (`file`, `kubernetes`) | `file` |
+| `SCANNER_SURFACE_SECRETS_ROOT` | Root path for file provider | `/etc/stellaops/secrets` |
+| `SCANNER_SURFACE_SECRETS_ALLOW_INLINE` | Allow inline secrets | `false` |
+
+For Helm deployments, configure via `values.yaml`:
+```yaml
+surface:
+  fs:
+    endpoint: "http://rustfs:8080"
+    bucket: "surface-cache"
+  cache:
+    root: "/var/lib/stellaops/surface"
+    quotaMb: 4096
+  tenant: "default"
+  secrets:
+    provider: "file"
+    root: "/etc/stellaops/secrets"
+```
+
+For Docker Compose, these variables are pre-configured in `docker-compose.airgap.yaml` with sensible defaults.
+
 **Advisory AI volume primer:** ship a tarball containing empty `queue/`, `plans/`, and `outputs/` directories plus their ownership metadata. During import, extract it onto the RWX volume used by `advisory-ai-web` and `advisory-ai-worker` so pods start with the expected directory tree even on air-gapped nodes.
 
 *Scanner core:* C# 12 on **.NET {{ dotnet }}**.