clawsec-nanoclaw

Original source / Raw SKILL.md

---
name: clawsec-nanoclaw
version: 0.0.3
description: Use when checking for security vulnerabilities in NanoClaw skills, before installing new skills, or when asked about security advisories affecting the bot
---

# ClawSec for NanoClaw

Security advisory monitoring that protects your WhatsApp bot from known vulnerabilities in skills and dependencies.

## Overview

ClawSec provides MCP tools that check installed skills against a curated feed of security advisories. It prevents installation of vulnerable skills, includes exploitability context for triage, and alerts you to issues in existing ones.

**Core principle:** Check before you install. Monitor what's running.

## When to Use

Use ClawSec tools when:
- Installing a new skill (check safety first)
- User asks "are my skills secure?"
- Investigating suspicious behavior
- Regular security audits
- After receiving security notifications

Do NOT use for:
- Code review (use other tools)
- Performance issues (different concern)
- General debugging

## MCP Tools Available

### Pre-Installation Check

```typescript
// Before installing any skill
const safety = await tools.clawsec_check_skill_safety({
  skillName: 'new-skill',
  skillVersion: '1.0.0'  // optional
});

if (!safety.safe) {
  // Show user the risks before proceeding
  console.warn(`Security issues: ${safety.advisories.map(a => a.id)}`);
}
```

### Security Audit

```typescript
// Check all installed skills (defaults to ~/.claude/skills in the container)
const result = await tools.clawsec_check_advisories({
  installRoot: '/home/node/.claude/skills'  // optional
});

if (result.matches.some((m) =>
  m.advisory.severity === 'critical' || m.advisory.exploitability_score === 'high'
)) {
  // Alert user immediately
  console.error('Urgent advisories found!');
}
```

### Browse Advisories

```typescript
// List advisories with filters
const advisories = await tools.clawsec_list_advisories({
  severity: 'high',               // optional
  exploitabilityScore: 'high'     // optional
});
```

## Quick Reference

| Task | Tool | Key Parameter |
|------|------|---------------|
| Pre-install check | `clawsec_check_skill_safety` | `skillName` |
| Audit all skills | `clawsec_check_advisories` | `installRoot` (optional) |
| Browse feed | `clawsec_list_advisories` | `severity`, `type`, `exploitabilityScore` (optional) |
| Verify package signature | `clawsec_verify_skill_package` | `packagePath` |
| Refresh advisory cache | `clawsec_refresh_cache` | (none) |
| Check file integrity | `clawsec_check_integrity` | `mode`, `autoRestore` (optional) |
| Approve file change | `clawsec_approve_change` | `path` |
| View baseline status | `clawsec_integrity_status` | `path` (optional) |
| Verify audit log | `clawsec_verify_audit` | (none) |

## Common Patterns

### Pattern 1: Safe Skill Installation

```typescript
// ALWAYS check before installing
const safety = await tools.clawsec_check_skill_safety({
  skillName: userRequestedSkill
});

if (safety.safe) {
  // Proceed with installation
  await installSkill(userRequestedSkill);
} else {
  // Show user the risks and get confirmation
  await showSecurityWarning(safety.advisories);
  if (await getUserConfirmation()) {
    await installSkill(userRequestedSkill);
  }
}
```

### Pattern 2: Periodic Security Check

```typescript
// Add to scheduled tasks
schedule_task({
  prompt: "Check advisories using clawsec_check_advisories and alert when critical or high-exploitability matches appear",
  schedule_type: "cron",
  schedule_value: "0 9 * * *"  // Daily at 9am
});
```

### Pattern 3: User Security Query

```
User: "Are my skills secure?"

You: I'll check installed skills for known vulnerabilities.
[Use clawsec_check_advisories]

Response:
✅ No urgent issues found.
- 2 low-severity/low-exploitability advisories
- All skills up to date
```

## Common Mistakes

### ❌ Installing without checking
```typescript
// DON'T
await installSkill('untrusted-skill');
```

```typescript
// DO
const safety = await tools.clawsec_check_skill_safety({
  skillName: 'untrusted-skill'
});
if (safety.safe) await installSkill('untrusted-skill');
```

### ❌ Ignoring exploitability context
```typescript
// DON'T: Use severity only
if (advisory.severity === 'high') {
  notifyNow(advisory);
}
```

```typescript
// DO: Use exploitability + severity
if (
  advisory.exploitability_score === 'high' ||
  advisory.severity === 'critical'
) {
  notifyNow(advisory);
}
```

### ❌ Skipping critical severity
```typescript
// DON'T: Ignore high exploitability in medium severity advisories
if (advisory.severity === 'critical') alert();
```

```typescript
// DO: Prioritize exploitability and severity together
if (advisory.exploitability_score === 'high' || advisory.severity === 'critical') {
  // Alert immediately
}
```

## Implementation Details

**Feed Source**: https://clawsec.prompt.security/advisories/feed.json

**Update Frequency**: Every 6 hours (automatic)

**Signature Verification**: Ed25519 signed feeds
**Package Verification Policy**: pinned key only, bounded package/signature paths

**Cache Location**: `/workspace/project/data/clawsec-advisory-cache.json`

See [INSTALL.md](./INSTALL.md) for setup and [docs/](./docs/) for advanced usage.

## Real-World Impact

- Prevents installation of skills with known RCE vulnerabilities
- Alerts to supply chain attacks in dependencies
- Provides actionable remediation steps
- Zero false positives (curated feed only)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### INSTALL.md

```markdown
# ClawSec for NanoClaw - Installation Guide

This guide shows how to add ClawSec security monitoring to your NanoClaw deployment.

## Overview

ClawSec provides security advisory monitoring for NanoClaw through:
- **MCP Tools**: Agents can check for vulnerabilities via `clawsec_check_advisories`
- **Advisory Feed**: Automatic monitoring of https://clawsec.prompt.security/advisories/feed.json
- **Signature Verification**: Ed25519-signed feeds ensure integrity
- **Exploitability Context**: Advisories include exploitability score and rationale for triage

## Prerequisites

- NanoClaw >= 0.1.0
- Node.js >= 18.0.0
- Write access to NanoClaw installation directory

## Installation Steps

### 1. Copy Skill Files

Copy the `clawsec-nanoclaw` skill directory to your NanoClaw installation:

```bash
# From the ClawSec repository
cp -r skills/clawsec-nanoclaw /path/to/your/nanoclaw/skills/
```

### 2. Integrate MCP Tools

Add the ClawSec MCP tools to your NanoClaw container agent runner.

**File**: `container/agent-runner/src/ipc-mcp-stdio.ts`

```typescript
// Add these imports at the top to register all ClawSec MCP tools:

// Advisory tools: clawsec_check_advisories, clawsec_check_skill_safety,
//                 clawsec_list_advisories, clawsec_refresh_cache
import '../../../skills/clawsec-nanoclaw/mcp-tools/advisory-tools.js';

// Signature verification: clawsec_verify_skill_package
import '../../../skills/clawsec-nanoclaw/mcp-tools/signature-verification.js';

// Integrity monitoring: clawsec_check_integrity, clawsec_approve_change,
//                       clawsec_integrity_status, clawsec_verify_audit
import '../../../skills/clawsec-nanoclaw/mcp-tools/integrity-tools.js';
```

Each file calls `server.tool()` directly to register its tools. The `server`,
`writeIpcFile`, `TASKS_DIR`, and `groupFolder` variables must be available in
the scope where these files are imported (they are declared as ambient globals
in each tool file).

### 3. Integrate IPC Handlers

Add the host-side IPC handlers for ClawSec operations.

**File**: `src/ipc.ts`

```typescript
// Add these imports at the top
import { handleAdvisoryIpc } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
import { SkillSignatureVerifier } from '../skills/clawsec-nanoclaw/host-services/skill-signature-handler.js';

// Initialize these once in host startup and pass through deps
const advisoryCacheManager = new AdvisoryCacheManager('/workspace/project/data', logger);
const signatureVerifier = new SkillSignatureVerifier();

// In processTaskIpc switch:
case 'refresh_advisory_cache':
case 'verify_skill_signature':
  await handleAdvisoryIpc(
    data,
    { advisoryCacheManager, signatureVerifier },
    logger,
    sourceGroup
  );
  break;
default:
  // existing task handling
}
```

### 4. Start Advisory Cache Service

Add the advisory cache manager to your host services.

**File**: `src/index.ts` (or your main entry point)

```typescript
import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';

// Start the service when your host process starts
async function main() {
  // ... your existing initialization ...

  // Initialize cache manager and prime it at startup
  const advisoryCacheManager = new AdvisoryCacheManager('/workspace/project/data', logger);
  await advisoryCacheManager.initialize();

  // Recommended refresh cadence (6h)
  setInterval(() => {
    advisoryCacheManager.refresh().catch((error) => {
      logger.error({ error }, 'Periodic advisory cache refresh failed');
    });
  }, 6 * 60 * 60 * 1000);

  // ... rest of your startup ...
}
```

### 5. Restart NanoClaw

Restart your NanoClaw instance to load the new MCP tools and services:

```bash
# Stop NanoClaw
docker-compose down

# Start with new configuration
docker-compose up -d
```

## Verification

Test that ClawSec is working:

### 1. Check MCP Tools Available

From within a NanoClaw agent session, the following tools should be available:

**Advisory Tools** (mcp-tools/advisory-tools.ts):
- `clawsec_check_advisories` - Scan installed skills for vulnerabilities
- `clawsec_check_skill_safety` - Pre-installation safety check
- `clawsec_list_advisories` - List all advisories with filtering
- `clawsec_refresh_cache` - Request immediate advisory cache refresh

**Signature Verification** (mcp-tools/signature-verification.ts):
- `clawsec_verify_skill_package` - Verify Ed25519 signature on skill packages
  - Uses pinned ClawSec public key (no runtime key override)
  - Accepts staged package/signature paths only under `/tmp`, `/var/tmp`, `/workspace/ipc`, `/workspace/project/data`, `/workspace/project/tmp`, `/workspace/project/downloads`

**Integrity Monitoring** (mcp-tools/integrity-tools.ts):
- `clawsec_check_integrity` - Check protected files for unauthorized changes
- `clawsec_approve_change` - Approve intentional file modification as new baseline
- `clawsec_integrity_status` - View current baseline status
- `clawsec_verify_audit` - Verify audit log hash chain integrity

### 2. Test Advisory Checking

Ask your NanoClaw agent:
```
Check if any of my installed skills have security advisories
```

The agent should use the `clawsec_check_advisories` tool and report results.

### 3. Check Advisory Cache

Verify the cache file was created:
```bash
cat /workspace/project/data/clawsec-advisory-cache.json
```

You should see:
- `feed`: Array of advisories
- `fetchedAt`: Timestamp of last update
- `verified`: Should be `true`
- `publicKeyFingerprint`: SHA-256 fingerprint of the pinned signing key

## Usage Examples

### Agent Commands

Once installed, your NanoClaw agents can:

**Check for vulnerabilities:**
```
Scan my installed skills for security issues
```

**Pre-installation check:**
```
Is it safe to install [email protected]?
```

**List all advisories:**
```
Show me all ClawSec security advisories
```

### Manual Tool Invocation

You can also call the MCP tools directly from agent code:

```typescript
// Check all installed skills
const result = await tools.clawsec_check_advisories({
  installRoot: '/home/node/.claude/skills'
});

// Check specific skill before installation
const safetyCheck = await tools.clawsec_check_skill_safety({
  skillName: 'risky-skill',
  skillVersion: '1.0.0'
});
```

## Configuration

### Cache Location

Default: `/workspace/project/data/clawsec-advisory-cache.json`

To change, pass a different data directory path to `new AdvisoryCacheManager(dataDir, logger)`.

### Refresh Interval

Default: 6 hours

To change, update the `setInterval(...)` duration (in milliseconds) in host startup.

### Feed URL

Default: `https://clawsec.prompt.security/advisories/feed.json`

To use a mirror or custom feed, update `FEED_URL` in `skills/clawsec-nanoclaw/host-services/advisory-cache.ts`.

## Platform-Specific Advisories

ClawSec advisories can target specific platforms:

- **`platforms: ["nanoclaw"]`**: Only affects NanoClaw
- **`platforms: ["openclaw"]`**: Only affects OpenClaw/MoltBot
- **`platforms: ["openclaw", "nanoclaw"]`**: Affects both
- **No `platforms` field**: Applies to all platforms

Platform metadata is preserved in advisory records and can be filtered by your policy layer.

## Security

### Signature Verification

All advisory feeds are Ed25519 signed. The public key is pinned in:
```
skills/clawsec-nanoclaw/advisories/feed-signing-public.pem
```

Feeds failing signature verification are rejected.

### Cache Integrity

The advisory cache includes:
- Cryptographic signature of feed contents
- Verification status
- Timestamp of last successful fetch

Never manually edit the cache file - it will break signature verification.

## Troubleshooting

### Tools Not Appearing

**Problem**: MCP tools not showing up in agent

**Solution**:
1. Check that you added the import and registration in `ipc-mcp-stdio.ts`
2. Restart the container
3. Check container logs for import errors

### Cache Not Updating

**Problem**: Advisory cache is empty or stale

**Solution**:
1. Check that `AdvisoryCacheManager.initialize()` is called in your host entry point
2. Verify network access to `clawsec.prompt.security`
3. Check host logs for fetch errors
4. Manually trigger: `curl https://clawsec.prompt.security/advisories/feed.json`

### Signature Verification Failing

**Problem**: Cache shows `"verified": false`

**Solution**:
1. Ensure public key file exists at correct path
2. Check file permissions (should be readable)
3. Verify feed URL is correct (not using HTTP instead of HTTPS)
4. Check for corrupted downloads (try clearing cache and refetching)

### IPC Communication Issues

**Problem**: Tools return errors about IPC

**Solution**:
1. Verify IPC handlers are registered in `src/ipc.ts`
2. Check that IPC directory exists and is writable
3. Ensure host process is running
4. Check host logs for handler errors

## Uninstallation

To remove ClawSec from NanoClaw:

1. Remove MCP tool registration from `ipc-mcp-stdio.ts`
2. Remove IPC handler registration from `src/ipc.ts`
3. Remove `AdvisoryCacheManager` initialization from host entry point
4. Delete the skill directory: `rm -rf skills/clawsec-nanoclaw`
5. Delete the cache file: `rm /workspace/project/data/clawsec-advisory-cache.json`
6. Restart NanoClaw

## Support

- **Documentation**: https://clawsec.prompt.security/
- **Issues**: https://github.com/prompt-security/clawsec/issues
- **Security**: [email protected]

## License

AGPL-3.0-or-later

---

**Questions?** Open an issue or check the main ClawSec documentation.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# ClawSec for NanoClaw

ClawSec now supports NanoClaw, a containerized WhatsApp bot powered by Claude agents.

## What Changed

### Advisory Feed Monitoring
- **NVD CVE Pipeline**: Now monitors for NanoClaw-specific keywords
  - "NanoClaw", "WhatsApp-bot", "baileys" (WhatsApp library)
  - Container-related vulnerabilities
- **Platform Targeting**: Advisories can specify `platforms: ["nanoclaw"]` for NanoClaw-specific issues

### Keywords Added
The CVE monitoring now includes:
- `NanoClaw` - Direct product name
- `WhatsApp-bot` - Core functionality
- `baileys` - WhatsApp client library dependency

## Advisory Schema

Advisories now support optional `platforms` field:

```json
{
  "id": "CVE-2026-XXXXX",
  "platforms": ["openclaw", "nanoclaw"],
  "severity": "critical",
  "type": "prompt_injection",
  "affected": ["[email protected]"],
  "action": "Update to version 1.0.1"
}
```

**Platform values:**
- `"openclaw"` - Affects OpenClaw/ClawdBot/MoltBot only
- `"nanoclaw"` - Affects NanoClaw only
- `["openclaw", "nanoclaw"]` - Affects both platforms
- (empty/missing) - Applies to all platforms (backward compatible)

## ClawSec NanoClaw Skill

ClawSec provides a complete security skill for NanoClaw deployments:

**Location**: `skills/clawsec-nanoclaw/`

### Features

- **9 MCP Tools** for agents to manage security:
  - `clawsec_check_advisories` - Scan installed skills for vulnerabilities
  - `clawsec_check_skill_safety` - Pre-installation safety checks
  - `clawsec_list_advisories` - Browse advisory feed with filtering
  - `clawsec_refresh_cache` - Request immediate advisory cache refresh
  - `clawsec_verify_skill_package` - Verify Ed25519 signatures on skill packages
  - `clawsec_check_integrity` - Check protected files for unauthorized changes
  - `clawsec_approve_change` - Approve intentional file modifications
  - `clawsec_integrity_status` - View file baseline status
  - `clawsec_verify_audit` - Verify audit log hash chain

- **Advisory Cache Service**: Host-managed feed fetching with signature validation
- **Signature Verification**: Ed25519-signed feeds ensure integrity
- **Exploitability Context**: Surfaces `exploitability_score` and rationale to reduce alert fatigue
- **IPC Communication**: Container-safe host communication

### Installation

1. Copy the skill to your NanoClaw deployment:
   ```bash
   cp -r skills/clawsec-nanoclaw /path/to/nanoclaw/skills/
   ```

2. Follow the detailed guide at `skills/clawsec-nanoclaw/INSTALL.md`

### Quick Integration

The skill integrates into three places:

**1. MCP Tools** (container):
```typescript
// container/agent-runner/src/ipc-mcp-stdio.ts
import '../../../skills/clawsec-nanoclaw/mcp-tools/advisory-tools.js';
```

**2. IPC Handlers** (host):
```typescript
// src/ipc.ts
import { handleAdvisoryIpc } from '../skills/clawsec-nanoclaw/host-services/ipc-handlers.js';
```

**3. Cache Service** (host):
```typescript
// src/index.ts
import { AdvisoryCacheManager } from '../skills/clawsec-nanoclaw/host-services/advisory-cache.js';
```

### Advisory Feed

NanoClaw consumes the same feed as OpenClaw:
```
https://clawsec.prompt.security/advisories/feed.json
```

The feed is Ed25519 signed and automatically fetched by the cache service.

## Team Credits

This integration was developed by a team of 8 specialized agents coordinated to adapt ClawSec for NanoClaw:

- **pioneer-repo-scout** - ClawSec architecture analysis
- **pioneer-nanoclaw-scout** - NanoClaw architecture analysis
- **architect** - Integration design and coordination
- **advisory-specialist** - Advisory feed integration
- **integrity-specialist** - File integrity design
- **installer-specialist** - Signature verification implementation
- **tester** - Test infrastructure and validation
- **documenter** - Documentation

Total contribution: 3000+ lines of code and comprehensive design documents.

## What's Included

The `clawsec-nanoclaw` skill provides:

- **1,730 lines** of production-ready TypeScript code
- **MCP Tools** (350 lines): Agent-facing vulnerability checking
- **Advisory Cache** (492 lines): Automatic feed fetching and caching
- **Signature Verification** (387 lines): Ed25519 signature validation
- **Advisory Matching** (289 lines): Skill-to-vulnerability correlation
- **IPC Handlers** (212 lines): Container-to-host communication
- **Complete Documentation**: Installation guide, usage examples, troubleshooting

## Future Enhancements

Planned features for future releases:
- File integrity monitoring (soul-guardian adaptation for containers)
- Real-time advisory alerts via WebSocket
- WhatsApp-native security alert formatting
- Behavioral analysis and anomaly detection
- Custom/private advisory feed support

## Documentation

- [Skill Documentation](skills/clawsec-nanoclaw/SKILL.md) - Features and architecture
- [Installation Guide](skills/clawsec-nanoclaw/INSTALL.md) - Detailed setup instructions
- [ClawSec Main README](README.md) - Overall ClawSec documentation
- [Security & Signing](../../wiki/security-signing-runbook.md) - Signature verification details

## Support

- **Issues**: https://github.com/prompt-security/clawsec/issues
- **Security**: [email protected]
- NanoClaw Repository: https://github.com/qwibitai/nanoclaw

```