# Security Baseline (Messaging + Core)

Armorer now enforces a default security baseline for Telegram/Signal gateway flows and core task processing.

## What is enforced

1. Admin allowlist for Telegram operations.
2. Per-user Telegram rate limiting.
3. Mandatory confirmation for high-risk actions.
4. HMAC signing for gateway -> core task files (optional but recommended).
5. Core-side signature verification and rejection of invalid tasks.
6. Guard input blocking policy for high-risk flags and high-confidence detections.
7. Vault-only secret reads (no secret fallback to `.env` for runtime secret retrieval).
8. Security audit log for auth, confirmation, signature, and processing events.
9. Backlog detection and explicit poller failure logging.
10. OTEL-first agent runtime monitoring (OpenClaw defaults to OTEL mode).

## Vault / config keys

### Access control

- `ARMORER_TELEGRAM_ADMIN_USER_IDS`
  - Comma-separated Telegram user IDs allowed to control Armorer.
- `ARMORER_TELEGRAM_ADMIN_CHAT_IDS`
  - Comma-separated Telegram chat IDs allowed to control Armorer.
- `ARMORER_ADMIN_USER_IDS`
  - Fallback global allowlist for user IDs.
- `ARMORER_ADMIN_CHAT_IDS`
  - Fallback global allowlist for chat IDs.

`TELEGRAM_ALERT_CHAT_ID` is automatically added to allowed chat IDs when set.

### Rate limiting

- `ARMORER_TELEGRAM_RATE_LIMIT_COUNT`
  - Max requests per user within time window. Default: `15`.
- `ARMORER_TELEGRAM_RATE_LIMIT_WINDOW_S`
  - Rate limit window in seconds. Default: `60`.

### Confirmation gate

- `ARMORER_CONFIRM_TTL_S`
  - Confirmation token lifetime in seconds. Default: `60`.

High-risk prompts require an explicit inline-button or in-thread `confirm` approval.
`cancel` is supported for aborting a pending confirmation, and `/confirm <token>` remains available for explicit token-based approval.

### Task signing

- `ARMORER_TASK_SIGNING_KEY` (secret; store in vault)
  - Enables HMAC-SHA256 signing of inbox tasks by gateway.
  - Core verifies signatures and rejects tampered/unsigned tasks.

## LLM Guard policy defaults

`~/.armorer/guard_settings.json` includes policy defaults:

- `input_block_enabled`: `true`
- `input_block_confidence_threshold`: `0.85`
- `block_on_flags`: prompt-injection, exfiltration, destructive, safety bypass categories

Armorer still redacts sensitive content, stores sanitized history, and emits guard notifications.

## Audit and operations artifacts

- `~/.armorer/security_audit.jsonl`
  - Security events from gateway/core (denied auth, rate-limited, confirmation lifecycle, signature failures, backlog).
- `~/.armorer/telegram_pending_confirmations.json`
  - Pending confirmation tokens and expirations.
- `~/.armorer/guard_settings.json`
  - Guard scanner and policy toggles.
- `~/.armorer/otel_events/*.jsonl`
  - OTEL-derived event stream consumed by Armorer for runtime guard monitoring.

## OTEL-first monitoring

- OpenClaw playbook now defaults to `monitoring_mode: hybrid`.
- In `hybrid` mode, Armorer uses OTEL as the primary listener for guard detection and auto-steer.
- File monitoring remains active for redaction overwrite of runtime artifacts (session/log files).
- When auto-steer is triggered, Armorer sets guard control state and injects a `source=armorer_guard` steering note into recent runtime `.jsonl` history files.
- Armorer consumes JSONL event feeds under `~/.armorer/otel_events/` and applies guard inspection to those events.
- File-first mode remains available by switching agent `monitoring_mode` to `file`.

### Collector bridge

Set up local OTLP/HTTP ingestion bridge:

```bash
armorer gateway otel setup
armorer gateway otel status
```

This bridge is agent-agnostic: any installed agent that emits OTLP/HTTP can send telemetry to Armorer's endpoint (`http://127.0.0.1:4318` by default).

## Recommended setup

1. Set admin allowlists (user/chat IDs).
2. Set `ARMORER_TASK_SIGNING_KEY` in vault.
3. Keep LLM Guard enabled with default block policy.
4. Monitor `security_audit.jsonl` and daily reports.
5. Rotate bot/API tokens periodically.
