clawsec/skills/clawsec-nanoclaw/INSTALL.md

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:

# 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

// 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

// 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)

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:

# 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:

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 skill-name@1.0.0?

List all advisories:

Show me all ClawSec security advisories

Manual Tool Invocation

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

// 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: security@prompt.security

License

AGPL-3.0-or-later

---

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