Skip to navigation
SDK

SDK Overview

Overview

The @pensar/apex npm package is both the pensar CLI and a TypeScript SDK. The SDK exposes the same agents the TUI and headless CLI use: full pentests, targeted pentests, attack surface mapping, authentication, threat modeling, and patching. It also includes a client for the Pensar Console API.

Use the SDK when you want to:

  • Run Apex agents from your own CI jobs, scripts, or services
  • Stream agent output into your own UI, logs, or database
  • Combine individual agents (for example, map the attack surface, then run targeted pentests on selected endpoints)
  • Read and update Pensar Console issues, pentests, apps, and knowledge programmatically

Authorization Required: Only test systems you own or have explicit authorization to test.

Installation

npm install @pensar/apex

The package ships ESM modules and TypeScript declarations. It requires Node.js 18 or later, or Bun 1.0 or later.

Importing

Every module is published as a package subpath, so import only the parts you need:

import { runPentestAgent } from "@pensar/apex/core/api";
import { sessions } from "@pensar/apex/core/session";

The package root also re-exports each module as a namespace. This is convenient for exploration, but subpath imports keep your bundle smaller:

import { api, session } from "@pensar/apex";
await api.runPentestAgent({ /* ... */ });
await session.sessions.create({ /* ... */ });

Core modules

Import pathWhat it provides
@pensar/apex/core/apiAgent runners (runPentestAgent, runTargetedPentestAgent, runAttackSurfaceAgent, …) and the Pensar Console API client
@pensar/apex/core/sessionsessions — create, load, and delete the sessions that hold agent artifacts
@pensar/apex/core/eventBusAgentEventBus — typed stream of agent text, tool calls, and lifecycle events
@pensar/apex/core/configconfig — read and update ~/.pensar/config.json
@pensar/apex/core/aibuildAuthConfig and model/provider types
@pensar/apex/api/targetedPenteststartTargetedPentestAgent — targeted pentest with an explicit teardown handle
@pensar/apex/agents/offSecAgentTool name lists (ALL_TOOL_NAMES, SKILL_TOOL_NAMES) and agent input types

The package.json exports map lists further subpaths (findings registry, CVSS scoring, observability, tool backends). Those are lower-level building blocks and are not covered by this reference yet.

How the SDK fits together

Every agent run follows the same shape:

1

Resolve credentials

Load your AI provider keys with config.get() and pass them to agents as authConfig: buildAuthConfig(cfg). See Configuration.

2

Create a session

Call sessions.create() to allocate a directory under ~/.pensar/sessions/ for findings, POCs, and logs. See sessions.

3

Run an agent

Call a runner such as runPentestAgent() with a target, model, and session. Pass an AgentEventBus to stream progress. See AgentEventBus.

4

Read the results

Each runner resolves with structured results (for example, findings) plus paths to the artifacts it wrote into the session.

Next steps

Quickstart

Run your first pentest from TypeScript

runPentestAgent

Full reference for the pentest runner