Security Architecture
ClawNex is built to give operators control over AI agent traffic without forcing them into a hosted SaaS control plane. The security model is local-first, audited, and designed around explicit trust boundaries.
This is the public security architecture. It describes how ClawNex protects operator environments without exposing internal test reports or private implementation notes.
Security Principles
| Principle | How ClawNex Applies It |
|---|---|
| Fail closed | If the proxy path is unavailable, model traffic does not silently bypass inspection |
| Observe first | Operators can run in observe mode before switching to active blocking |
| Least privilege | Dashboard and LiteLLM bind locally; public access goes through Caddy |
| Audit everything important | Auth events, config changes, shield decisions, API keys, and break-glass actions are logged |
| Explicit exceptions | Break-glass is time-limited, reason-required, and audited |
| Local control | Operational data stays on the install host unless the operator exports it |
Threats ClawNex Targets
| Threat | ClawNex Control |
|---|---|
| Prompt injection | ClawNex Shield Rules scan inbound prompts before provider calls |
| Jailbreak attempts | Known jailbreak and persona-splitting patterns are detected |
| Secret exfiltration | API keys, private keys, tokens, and credential patterns are detected |
| Dangerous tool or file access | Sensitive path and command patterns are scored and alerted |
| C2 and webhook exfiltration | Network exfiltration indicators are detected |
| Encoded or hidden payloads | Encoding, Unicode, zero-width, and steganography patterns are detected |
| Output leakage | Responses are scanned for private keys, passwords, internal IPs, and related leak patterns |
| Weak host posture | Host Security checks surface local hardening gaps |
| Poor trust boundaries | Trust Audit maps reachable surfaces and risky access paths |
Detection Model
ClawNex scans traffic in three places:
| Layer | Blocking Capability | Purpose |
|---|---|---|
| Pre-call prompt scan | Yes, when shield mode is BLOCK | Stop dangerous prompts before model execution |
| Post-call response scan | No | Detect and record possible data leakage |
| Retroactive session scan | No | Find activity from session logs and non-proxy paths |
This gives operators both prevention and evidence.
Verdicts
ClawNex Shield Rules produce a verdict:
| Verdict | Meaning |
|---|---|
| ALLOW | No meaningful detection |
| REVIEW | Suspicious, but not automatically blocked |
| BLOCK | High-confidence or high-severity detection |
In OBSERVE mode, ClawNex records the verdict but does not reject traffic. In BLOCK mode, block verdicts are rejected before the prompt reaches the model.
Authentication and Access
Public-facing installs run with RBAC enabled.
RBAC includes:
- first-admin setup secret
- operator accounts
- five built-in roles
- permission-checked API routes
- session cookies
- progressive lockout
- CSRF protection for state-changing internal routes
- audit events for significant auth and access-control actions
Supported sign-in methods:
| Method | Purpose |
|---|---|
| Local password | Always-available break-glass login path |
| Passkeys | Phishing-resistant operator authentication |
| GitHub OAuth | Team identity convenience |
| Magic link email | Passwordless sign-in when mail is configured |
Local-only installs can run without RBAC, but that mode is intended only for localhost use.
API Security
ClawNex exposes three API surfaces:
| Surface | Authentication |
|---|---|
| Internal dashboard API | Session-authenticated when RBAC is enabled |
| Public REST API | API key via X-ClawNex-Key or Authorization: Bearer |
| OpenAI-compatible chat endpoint | API key plus shield scanning |
API keys are created from the dashboard and masked after creation. Operators should treat public API keys like production credentials.
Network Posture
Expected public VPS posture:
| Port | Exposure | Role |
|---|---|---|
| 80 | Public | HTTP redirect and ACME challenge |
| 443 | Public | HTTPS dashboard access |
| 5001 | Localhost only | Dashboard backend |
| 4001 | Localhost only | LiteLLM proxy |
Ports 5001 and 4001 should not be opened directly to the internet.
Break-Glass
Break-glass is the emergency bypass path. It exists because operational systems sometimes need recovery before perfect policy enforcement.
Break-glass behavior:
- requires an authorized operator
- requires a reason
- is time-limited
- is audited
- creates visible security state
- should be reviewed after use
When break-glass is active, traffic is not protected by shield enforcement. It should be treated as an incident-response mechanism, not a normal operating mode.
Audit and Evidence
ClawNex records audit events for:
- operator login and logout
- failed login attempts
- setup completion
- provider changes
- shield mode changes
- break-glass activation and expiration
- API key creation and revocation
- policy and rule changes
- risk acceptance changes
- report generation
The audit trail is designed to support operator review, incident reconstruction, and compliance evidence.
Data Handling
ClawNex favors privacy over full prompt replay. The product records security findings, metadata, hashes, scores, excerpts, and evidence needed for operator decisions. It is not intended to become a warehouse of full agent conversations.
Operators should still treat the local database and logs as sensitive operational data.
Supply Chain Posture
ClawNex pins critical runtime dependencies and uses a known LiteLLM version in the installer path. ClawNex Shield Rules are built in. The installer should not imply that it downloads rule logic from third-party security-rule repositories during setup.
Operator Responsibilities
Operators remain responsible for:
- protecting API keys
- keeping the host patched
- securing DNS and TLS endpoints
- choosing appropriate model providers
- reviewing break-glass events
- rotating credentials after suspected compromise
- configuring RBAC for team use
- keeping OpenClaw and ClawNex updated
ClawNex gives visibility and controls. It does not replace basic host, identity, and credential hygiene.