Tool Security

​

SSRF Guard

​

Validation Steps

​

Allowed Protocols

• http:
• https:

​

Blocked IP Ranges

​

Cloud Metadata IPs

​

DNS Resolution

​

ValidatedUrl Interface

interface ValidatedUrl {
  hostname: string;  // Original hostname from the URL
  ip: string;        // DNS-resolved IP address
  url: URL;          // Parsed URL object
}

​

Usage Example

import { validateUrl } from "@comis/core";

const result = await validateUrl("https://api.example.com/data");
if (!result.ok) {
  // URL is blocked -- do not fetch
  logger.warn({ err: result.error }, "SSRF validation failed");
  return;
}

// Safe to fetch -- use result.value.url
const response = await fetch(result.value.url.toString());

​

Tool Policy

​

Built-in Profiles

​

Tool Groups

​

Resolution Precedence

1. Profile baseline — start with the profile’s tool set
2. Allow additions — add explicitly allowed tools and expand group references
3. Deny removals — remove denied tools (deny always takes precedence)

​

MCP Export Policy

​

obs_explain — read-only incident report, allowlist-gated

• The allowlist IS the granted permission — not admin trust. obs_explain does not invoke the admin-gated obs.explain RPC. Its dispatch branch runs the report assembler directly under daemon authority, bypassing the trust-flag indirection entirely. No _trustLevel:"admin" is ever injected, and the admin RPC’s own ["admin"] gate is unchanged for non-MCP callers. A client without obs_explain allowlisted is rejected (default-deny).
• Digest-only and bounded. The report is summary-bounded (no raw tool bodies, no raw message content cross the boundary) and flows through wrapExternalContent — the calling agent receives it wrapped in a SECURITY NOTICE block + untrusted-content markers, like any other external text.
• Read-only + rate-limited. The tool performs no mutation, and the standard per-client per-tool minute-bucket rate limit applies.

​

Content Scanner

​

Scan Categories

​

Severity Levels

• CRITICAL: Patterns that indicate active exploitation attempts (exec injection, reverse shells, crypto mining, base64 decode piping, XML breakout)
• WARN: Patterns that are suspicious but may have legitimate uses (environment harvesting, curl piping, long encoded strings, mining pool domains)

​

Scan Result

interface ContentScanResult {
  clean: boolean;       // true if no patterns matched
  findings: ContentScanFinding[];
}

interface ContentScanFinding {
  ruleId: string;       // e.g., "EXEC_SUBSHELL"
  category: ScanCategory;
  severity: "CRITICAL" | "WARN";
  description: string;
  matchedText: string;  // truncated to 100 chars
  position: number;     // character offset in content
  lineNumber: number;   // 1-based line number in the original content
}

​

Sanitization Pipeline

​

Pipeline Steps

​

Sanitization Result

interface SanitizeResult {
  body: string;                  // Final sanitized content
  htmlCommentsStripped: number;  // Count for audit
  truncated: boolean;            // Whether size limit was hit
  tagBlockDetected: boolean;     // Unicode tag block bypass detected
}

​

Audit Wrapper

{
  timestamp: number;
  agentId: string;
  tenantId: string;
  actionType: string;        // e.g., "file.write", "web.fetch"
  classification: string;    // "read" | "mutate" | "destructive"
  outcome: "success" | "failure";
  metadata: {
    durationMs: number;
    toolName?: string;
    // Additional context per tool
  };
}