clawsec/wiki/modules/nanoclaw-integration.md

Module: NanoClaw Integration

Responsibilities

• Port ClawSec advisory/signature logic into NanoClaw host+container architecture.
• Provide MCP tools that expose advisory checks, signature verification, and integrity monitoring.
• Maintain host-side cached advisory state with TLS/signature enforcement and IPC-triggered refresh.
• Protect critical NanoClaw files with baseline drift detection and hash-chained audit trails.

Platform Support Summary (migrated from README)

ClawSec supports NanoClaw as a containerized WhatsApp-bot deployment model.

clawsec-nanoclaw skill scope

• Location: skills/clawsec-nanoclaw/
• 9 MCP tools for advisory checks, package-safety checks, signature verification, and integrity monitoring.
• Automatic advisory feed refresh/caching on a recurring cadence.
• Platform filtering for NanoClaw-relevant advisories.
• IPC-based host/container communication model.

NanoClaw advisory coverage

The feed and matching pipeline include NanoClaw-relevant terms:

• NanoClaw
• WhatsApp-bot
• baileys

Advisories can be explicitly platform-scoped via:

• platforms: ["nanoclaw"]

Quick integration checklist

1. Copy skill files to the NanoClaw deployment.
2. Integrate MCP tools in the container runtime.
3. Configure host IPC handlers and advisory cache service.
4. Restart NanoClaw services.

Install guide:

• skills/clawsec-nanoclaw/INSTALL.md

Key Files

• skills/clawsec-nanoclaw/skill.json: NanoClaw package contract and MCP tool registry.
• skills/clawsec-nanoclaw/lib/signatures.ts: secure fetch and Ed25519 verification primitives.
• skills/clawsec-nanoclaw/lib/advisories.ts: feed load and advisory matching helpers.
• skills/clawsec-nanoclaw/host-services/advisory-cache.ts: host cache manager.
• skills/clawsec-nanoclaw/host-services/ipc-handlers.ts: IPC request dispatch for advisory/signature tasks.
• skills/clawsec-nanoclaw/host-services/skill-signature-handler.ts: package signature verification service.
• skills/clawsec-nanoclaw/guardian/integrity-monitor.ts: baseline/diff/restore/audit engine.
• skills/clawsec-nanoclaw/mcp-tools/*.ts: container-side tool definitions.

Public Interfaces

Interface	Context	Notes
clawsec_check_advisories	MCP tool	Lists advisories affecting installed skills.
clawsec_check_skill_safety	MCP tool	Returns install recommendation for a specific skill.
clawsec_verify_skill_package	MCP tool	Verifies detached package signature through host IPC.
clawsec_check_integrity	MCP tool	Runs integrity check, optional auto-restore for critical targets.
IPC task verify_skill_signature	Host service	Returns structured verification response with error codes.
IPC task refresh_advisory_cache	Host service	Refreshes signed advisory cache on demand.

Inputs and Outputs

Inputs/outputs are summarized in the table below.

Type	Name	Location	Description
Input	Signed advisory feed	https://clawsec.prompt.security/advisories/feed.json(.sig)	Threat intelligence source for cache refresh.
Input	Package + signature files	Host filesystem paths	Pre-install package authenticity checks.
Input	Integrity policy	guardian/policy.json	Per-path mode and priority controls.
Output	Advisory cache	/workspace/project/data/clawsec-advisory-cache.json	Host-managed verified advisory data.
Output	Verification results	/workspace/ipc/clawsec_results/*.json	IPC response payload for tool calls.
Output	Integrity state	.../soul-guardian/	Baselines, snapshots, patches, quarantine, audit logs.

Configuration

Setting	Default	Effect
Feed URL	Hosted ClawSec advisory endpoint	Primary remote source for advisory cache manager.
Cache TTL	5 minutes	Controls staleness threshold before requiring refresh.
Fetch timeout	10 seconds	Limits host network wait time.
Allowed domains	clawsec.prompt.security, prompt.security, raw.githubusercontent.com, github.com	Restricts remote fetch targets.
Integrity policy modes	restore, alert, ignore	Controls automatic restoration and alert-only behavior.

Example Snippets

// host-side signature verification dispatch
const result = await deps.signatureVerifier.verify({
  packagePath,
  signaturePath,
  publicKeyPem,
  allowUnsigned: allowUnsigned || false,
});

// integrity monitor drift handling
if (baseline.mode === 'restore' && autoRestore) {
  // quarantine modified file, restore approved snapshot, append audit event
}

Edge Cases

• Disallowed domains or non-HTTPS URLs are blocked by security policy wrappers.
• Missing signature files can be tolerated only when allowUnsigned is explicitly set.
• IPC result waits can timeout, causing conservative block recommendations.
• Integrity engine refuses symlink operations to reduce path-redirection attacks.
• Audit-chain validation can detect tampering or corruption in historical records.

Tests

Test Scope	File/Path	Notes
Type contracts	skills/clawsec-nanoclaw/lib/types.ts	Defines tool/IPC DB payload contracts.
Operational docs	skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md, skills/clawsec-nanoclaw/docs/INTEGRITY.md	Describes verification/integrity usage patterns.
Cross-module behavior	Reuses suite verification patterns	Signature/checksum primitives ported from suite logic.

Source References

• skills/clawsec-nanoclaw/skill.json
• skills/clawsec-nanoclaw/lib/types.ts
• skills/clawsec-nanoclaw/lib/signatures.ts
• skills/clawsec-nanoclaw/lib/advisories.ts
• skills/clawsec-nanoclaw/host-services/advisory-cache.ts
• skills/clawsec-nanoclaw/host-services/ipc-handlers.ts
• skills/clawsec-nanoclaw/host-services/skill-signature-handler.ts
• skills/clawsec-nanoclaw/host-services/integrity-handler.ts
• skills/clawsec-nanoclaw/guardian/integrity-monitor.ts
• skills/clawsec-nanoclaw/guardian/policy.json
• skills/clawsec-nanoclaw/mcp-tools/advisory-tools.ts
• skills/clawsec-nanoclaw/mcp-tools/signature-verification.ts
• skills/clawsec-nanoclaw/mcp-tools/integrity-tools.ts
• skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md
• skills/clawsec-nanoclaw/docs/INTEGRITY.md