Memory Scan

# memory-scan

**Security scanner for OpenClaw agent memory files**

Scans MEMORY.md, daily logs (memory/*.md), and workspace configuration files for malicious content, prompt injection, credential leakage, and dangerous instructions that could compromise user security.

## Purpose

Detect security threats embedded in agent memory:
- Malicious instructions to bypass guardrails
- Prompt injection patterns in stored memories
- Credential/secret leakage
- Data exfiltration commands
- Behavioral manipulation
- Security policy violations

## Usage

### On-Demand Scan

Scan all memory files:
```bash
python3 skills/memory-scan/scripts/memory-scan.py
```

Allow remote LLM analysis (redacted content only):
```bash
python3 skills/memory-scan/scripts/memory-scan.py --allow-remote
```

Scan specific file:
```bash
python3 skills/memory-scan/scripts/memory-scan.py --file memory/2026-02-01.md
```

Quiet mode (for automation):
```bash
python3 skills/memory-scan/scripts/memory-scan.py --quiet
```

JSON output:
```bash
python3 skills/memory-scan/scripts/memory-scan.py --json
```

### Scheduled Monitoring

#### Cron Job (Daily Security Audit)

Already included in safe-install daily audit - runs 2pm PT daily.

To add standalone cron:
```bash
bash skills/memory-scan/scripts/schedule-scan.sh
```

Requires:
- `OPENCLAW_ALERT_CHANNEL` (configured in OpenClaw)
- `OPENCLAW_ALERT_TO` (optional, for channels that require a recipient)

Creates cron job: daily at 3pm PT, sends alert only if threats found.

#### Heartbeat Integration

Add to HEARTBEAT.md:
```markdown
## Weekly Memory Scan

Every Sunday, run memory scan:
python3 skills/memory-scan/scripts/memory-scan.py --quiet
```

## Security Levels

- **SAFE** - No threats detected
- **LOW** - Minor concerns, proceed with awareness
- **MEDIUM** - Potential threat, review recommended
- **HIGH** - Likely threat, immediate review required
- **CRITICAL** - Active threat detected, quarantine recommended

## What It Scans

1. **MEMORY.md** - Long-ter...

# Memory-Scan - OpenClaw Memory Security Scanner

Security scanner for OpenClaw agent memory files. Detects malicious instructions, prompt injection, credential leakage, and other threats embedded in MEMORY.md, daily logs, and workspace configuration files.

## Prerequisites

- **Python 3** — check with `python3 --version`
- **API key** (for `--allow-remote` mode) — requires `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`

No pip install is needed — memory-scan uses only the Python standard library (`urllib`).

### Environment Variables

Create a `.env` file in the repository root with any needed keys:

| Variable | Required For | Description |
|----------|-------------|-------------|
| `OPENAI_API_KEY` | `--allow-remote` | OpenAI API key (uses gpt-4o-mini) |
| `ANTHROPIC_API_KEY` | `--allow-remote` | Anthropic API key (alternative to OpenAI) |
| `PROMPTINTEL_API_KEY` | Taxonomy refresh, reporting | MoltThreats / PromptIntel API key |

Pattern-based scanning requires **no keys** — it works out of the box with Python 3.

## Quick Start

### On-Demand Scan

Scan all memory files (local pattern matching only):
```bash
python3 skills/memory-scan/scripts/memory-scan.py
```

Scan with LLM analysis for deeper detection (redacted content sent to LLM):
```bash
python3 skills/memory-scan/scripts/memory-scan.py --allow-remote
```

> **Note:** Without `--allow-remote`, only local pattern matching runs (fast, no API calls). With `--allow-remote`, content is redacted and sent to an LLM for deeper analysis of prompt injection, prompt stealing, and other subtle threats.

### Scheduled Monitoring

Set up daily cron job (3pm PT):
```bash
bash skills/memory-scan/scripts/schedule-scan.sh
```

## What It Does

- **Scans** MEMORY.md, daily logs (last 30 days), and workspace config files
- **Detects** threats using local pattern matching (add `--allow-remote` for deeper LLM analysis on redacted content)
- **Alerts** via configured OpenClaw channel on MEDIUM/HIGH/CRITICAL findings
- **Quarantines*...