@darkmoon_ai/ai-sdk

Vercel AI SDK tools for Darkmoon, the open source (GPL-3.0) autonomous AI penetration testing platform. Give an AI agent the ability to launch a pentest campaign, follow its progress and read the validated findings.

Open source vs Pro (read this first)

Darkmoon's engine, CLI, agents, and SARIF/JSON export are open source. The REST API and web dashboard are Darkmoon Pro features. These tools talk to the Darkmoon Pro REST API (through @darkmoon_ai/client), so you need a reachable Darkmoon Pro instance to use them. With the open source CLI only, use the CLI or the GitHub Action and consume the SARIF/JSON output instead.

Install

npm install @darkmoon_ai/ai-sdk ai zod

Requires ai ^7 and zod, Node 18+.

Tools

Tool	What it does
darkmoonRunPentest	Launch an autonomous pentest campaign against an authorized target. Returns a runId immediately. Needs human approval by default.
darkmoonGetCampaignStatus	Status (queued, running, completed, stopped, failed), overall risk and severity counts, by campaignId or runId.
darkmoonListCampaigns	List campaigns, optionally filtered by status or target.
darkmoonGetFindings	List findings (title, severity, CVSS, category, CVE, MITRE ATT&CK id, endpoint, remediation), filterable by campaign, severity, category and status.

Usage

import { generateText, isStepCount } from 'ai';
import { createDarkmoonTools } from '@darkmoon_ai/ai-sdk';

const tools = createDarkmoonTools({
  // restrict what the model may ever attack (exact host or *.wildcard)
  allowedTargets: ['staging.example.com', '*.qa.example.com'],
});

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  tools,
  stopWhen: isStepCount(8),
  prompt: 'List my Darkmoon campaigns and summarize the critical and high findings of the latest completed one.',
});
console.log(text);

Configuration comes from options or environment variables:

Option	Env var	Meaning
pro.baseUrl	DARKMOON_API_URL	Base URL of your Darkmoon Pro API (with or without /api/v1). Required.
pro.token	DARKMOON_API_TOKEN	Bearer token (skips login).
pro.username / pro.password	DARKMOON_USERNAME / DARKMOON_PASSWORD	Login credentials, used when no token is given.

You can also pass your own client (any object with launchCampaign, getCampaignStatus, listCampaigns, listFindings, for example a configured DarkmoonClient from @darkmoon_ai/client).

Safety defaults

A pentest sends real attack traffic. Only test systems you own or are explicitly authorized to test.

• requireApproval (default true): darkmoonRunPentest uses the AI SDK needsApproval flag, so your application must approve each launch.
• allowedTargets: when set, any target (including targets[]) outside the list is refused before any API call is made. Set it.
• Findings are returned as compact summaries. Raw evidence (requests, responses, extracted data) is never exposed to the model, and secrets are scrubbed by @darkmoon_ai/client.
• maxFindings (default 50) bounds how much a single call can return.

API

• createDarkmoonTools(options) returns { darkmoonRunPentest, darkmoonGetCampaignStatus, darkmoonListCampaigns, darkmoonGetFindings }, ready to pass as tools.
• isTargetAllowed(target, allowed) and extractHost(target) are exported helpers.

Development

npm install
npm run typecheck
npm test
npm run build

License

MIT, see LICENSE. Darkmoon itself is GPL-3.0 and published by ASC-IT.