Hey everyone,
So, I've been wrestling with this exact problem for the last three months while trying to get a coherent threat model for my self-hosted Nano-Claw setup. I'd build a beautiful STRIDE diagram for my data flow, feel great about it, and then two weeks later during a test, I'd realize I'd made a critical assumption that wasn't written down anywhere. The classic one for me was assuming my Docker bridge network was isolated, completely forgetting I'd set a `macvlan` network on one container for "convenience" six months ago. 😅
For me, the breakthrough wasn't finding a single perfect tool, but creating a living document template that forces me to think in layers. I keep it as a `threat_model_assumptions.md` in the root of each project's repo now. The key is to separate *environmental* assumptions from *component* assumptions from *threat* assumptions.
Here's the basic structure I've landed on, stolen and adapted from a few places:
```markdown
## Project: Home-LAB-Nano-Claw-Agent
## Last Review: 2024-10-26
### A. Environmental & "Ground Truth" Assumptions
* Hardware: Single NVIDIA RTX 4090 with GPU passthrough to Docker. Assumes no other VMs on the host are competing for GPU memory.
* Host OS: Debian 12, unattended-upgrades enabled for security. Assumes the underlying kernel is not compromised.
* Network: Behind OPNsense firewall, VLAN 30 for "Lab". Assumes VLAN hopping is mitigated by switch configuration (untested assumption!).
* Physical: Server is in a locked basement. Assumption: Physical access implies total compromise.
### B. Deployment & Configuration Assumptions
* Docker Compose: Uses `runtime: nvidia` for all LLM containers. Assumes the `nvidia-container-toolkit` is correctly installed and not introducing vulnerabilities.
* Service: Nano-Claw's `config.yaml` has `local_only: true`. Assumption: The agent framework will respect this and not attempt external API calls.
* Dependencies: All models are pulled from Hugging Face. Assumes the model files have not been poisoned at source (a big, often overlooked one!).
### C. Operational & Behavioral Assumptions
* LLM Inference: The local LLM (Llama 3.1 70B) is not persistently malicious. Assumes prompt injection can only elicit harmful responses during an active session, not modify weights.
* Data Flow: Agent output to the "action queue" is sanitized by a regex filter. Assumption: The filter catches all dangerous shell command patterns.
* User: Only I interact with the web UI. Assumption: I will not intentionally perform prompt injection attacks from the authenticated interface (a trust boundary failure waiting to happen).
### D. "If This Fails" Explicit Statements
* If the GPU driver crashes, the Docker container will exit. It will NOT fall back to CPU silently.
* If the VLAN configuration fails, the lab network defaults to the primary LAN (catastrophic).
* If the regex filter misses a command, the `bash` wrapper is configured to run as a low-privilege `labuser`, not root.
```
The magic for me is in section **D**. Writing down the explicit failure mode next to the assumption makes me test those paths. It turns the assumption from an invisible thought into a testable condition.
I also run a simple script before each major deployment that greps for the word "Assum" in this file and spits it out in my console. It's a good ritual.
What does everyone else do? I'm sure there are better methods out there, and I'm painfully aware my template is a bit verbose. Have you found a way to keep this lean but still comprehensive, especially for smaller projects?
- Sam
Still learning, still breaking things.
That macvlan example hits close to home. It's exactly the kind of "temporary" config that becomes permanent and invalidates your entire perimeter model.
Your layered template approach is solid. I'd push it one step further and make the "Last Review" date a hard trigger for action. Tie it to a calendar reminder or a CI check that fails a PR if the file is older than, say, 90 days. A stale assumptions doc is as dangerous as none at all.
Also, add a "Change Log" section at the top. When you update an assumption, note what changed and why. If you find yourself constantly updating the same environmental assumption, it's a signal your architecture is too brittle.
--Priya
That Docker bridge network assumption is such a classic trap. Your layered template idea is gold. I do something similar, but I embed a lot of those assumptions right in the docker-compose.yml as comments, because that's the file I'm always touching. It's not a replacement for the full doc, but it catches me when I'm about to do something stupid.
For example, right above the network definitions:
```yaml
# --- SECURITY ASSUMPTIONS ---
# bridge_network 'app_net' is considered internal-only.
# 'traefik' is the ONLY container attached to both this and the external proxy network.
# Do NOT add ports: to other containers without reviewing.
# ----------------------------
networks:
app_net:
internal: true
```
It's noisy, but it works. Forces a pause.
Also, seconding the "Last Review" date as a hard trigger. I have a weekly homelab check-in in my calendar, and if that file is older than a month, it's the first task. Stale docs breed blind spots.
Keep your data local.
I see the logic of putting assumptions right in the compose file, but doesn't that just formalize the security theater? If you're the person who added the macvlan network for "convenience" six months ago, you're also the person who will skim or ignore the comment block you wrote. It becomes visual noise.
Relying on a weekly calendar check to review a stale doc is the kind of optimistic discipline that lasts about three weeks post-conference. The only thing that's worked for me is baking the assumption review into an actual gate - like a pre-commit hook that parses the compose file and yells if the '# SECURITY ASSUMPTIONS' header is older than the last network definition change. Otherwise it's just another nag.
Also, 'internal: true' is a great example of a documented assumption that the Docker runtime doesn't actually enforce. You're assuming the orchestrator respects the flag, which is a whole other layer.
The layered template is a strong approach, but you've identified the core weakness: those layers are only as valid as the attestations made about them. An assumption like "GPU passthrough is secure" is a statement about your build's supply chain and runtime integrity that should be signed and verified.
Your environmental assumptions are, a set of claims about your platform's provenance. I'd argue you should treat them with the same rigor as a software bill of materials. For each entry in your "Ground Truth" section, you need a supporting artifact. For example:
* "Hardware: Single NVIDIA RTX 4090" - This should be backed by an inventory SBOM from your provisioning system.
* "GPU passthrough to Docker" - This should reference a specific, versioned configuration file (e.g., `/etc/docker/daemon.json`) whose hash is recorded in a gittuf root of trust.
Otherwise, you're documenting an intention, not a verifiable state. The assumption becomes stale the moment you `apt upgrade` and a library changes, breaking your isolation boundary without a corresponding update to the markdown file. The review date is meaningless without a cryptographic link to the actual system state at that time.
Signed from commit to container.