sdk.md

SDK Usage

Use GoPlus AgentGuard as a library in your own project.

Installation

npm install @goplus/agentguard

Quick Start

import { createAgentGuard } from '@goplus/agentguard';

const { scanner, registry, actionScanner } = createAgentGuard();

Scan Code

const result = await scanner.scan({
  skill: {
    id: 'my-skill',
    source: 'github.com/org/skill',
    version_ref: 'v1.0.0',
    artifact_hash: '',
  },
  payload: { type: 'dir', ref: '/path/to/skill' },
});

console.log(result.risk_level); // 'low' | 'medium' | 'high' | 'critical'
console.log(result.hits);       // Array of detection rule matches

Evaluate Actions

const decision = await actionScanner.decide({
  actor: {
    skill: { id: 'my-skill', source: 'cli', version_ref: '1.0.0', artifact_hash: '' },
  },
  action: {
    type: 'exec_command',
    data: { command: 'rm -rf /' },
  },
  context: {
    session_id: 's1',
    user_present: true,
    env: 'prod',
    time: new Date().toISOString(),
  },
});

console.log(decision.decision); // 'allow' | 'deny' | 'confirm'

Trust Registry

// Register a skill
await registry.attest({
  skill: { id: 'bot', source: 'github.com/org/bot', version_ref: 'v1.0.0', artifact_hash: 'sha256:abc' },
  trust_level: 'trusted',
  capabilities: { network_allowlist: ['api.example.com'], filesystem_allowlist: [], exec: 'deny', secrets_allowlist: [] },
  review: { reviewed_by: 'admin', evidence_refs: [], notes: 'Verified safe' },
});

// Look up
const result = await registry.lookup({
  id: 'bot', source: 'github.com/org/bot', version_ref: 'v1.0.0', artifact_hash: 'sha256:abc',
});
console.log(result.effective_trust_level); // 'trusted'

API Reference

See the TypeScript types exported from @goplus/agentguard for full API details:

• SkillScanner — Static analysis engine
• SkillRegistry — Trust level management
• ActionScanner — Runtime action evaluator
• CAPABILITY_PRESETS — Predefined capability sets (none, read_only, trading_bot, defi)