Patching

Overview

The Patching API provides intelligent vulnerability remediation capabilities. It analyzes security findings, generates appropriate code fixes, verifies the patches through testing, and prepares pull request metadata. Key Features:

Automated patch generation for security vulnerabilities
Code analysis and dataflow understanding
Lint, type-check, and test verification
Sandbox support for isolated patching
Pull request metadata generation
Multiple file change support

runPatchingAgent

Run the patching agent to fix a security vulnerability in a codebase. Patching Workflow:

Analyze: Read and understand the vulnerability details
Locate: Find the vulnerable code in the codebase
Research: Understand the context and dataflow
Patch: Generate and apply appropriate fixes
Verify: Run lints, type-checks, and tests
Document: Prepare PR metadata with changes

import { runPatchingAgent } from '@pensar/apex/api/patching';

const result = await runPatchingAgent({
  cwd: '/path/to/project',
  vulnerability: {
    name: 'SQL Injection in User Search',
    severity: 'HIGH',
    description: 'User input is directly concatenated into SQL query',
    location: 'src/controllers/userController.ts',
    startLineNumber: 42,
    endLineNumber: 45,
  },
  model: 'claude-sonnet-4-20250514',
  session: sessionInfo,
});

console.log(`Patched ${result.filesChanged.length} files`);
console.log(`PR Title: ${result.prTitle}`);

Parameters

RunPatchingAgentInput

required

Configuration for the patching agent

Show RunPatchingAgentInput properties

string

required

Root path of the repository/codebase to patch

VulnerabilityDetails

required

Details about the vulnerability to fix

Show VulnerabilityDetails properties

string

required

Vulnerability name/title

string

required

Severity level (e.g., "CRITICAL", "HIGH", "MEDIUM", "LOW")

string

required

Detailed description of the vulnerability

string

File path where the vulnerability exists

number | null

Starting line number of vulnerable code

number | null

Ending line number of vulnerable code

string[]

CWE identifiers for the vulnerability (e.g., ["CWE-89"])

unknown

Optional dataflow analysis data

object

Proof-of-concept exploit information

Show poc properties

string

PoC script filename

string

PoC script contents

AIModel

required

AI model identifier (e.g., "claude-sonnet-4-20250514")

SessionInfo

required

Session object providing paths for logs, etc.

UnifiedSandbox

Optional pre-configured sandbox for isolated code execution. When provided, all file operations and command executions route through the sandbox instead of the local filesystem.

AIAuthConfig

Optional per-provider API key overrides

AbortSignal

AbortSignal to cancel patching mid-run

ConsumeCallbacks

Optional callbacks for stream consumption. Falls back to console logging if not provided.

Show ConsumeCallbacks properties

(delta) => void

Called for each text chunk streamed from the AI

(delta) => void

Called when the agent invokes a tool

(delta) => void

Called when a tool execution completes

(error) => void

Called when an error occurs

StreamTextOnStepFinishCallback

Callback fired after each agent step completes

Response

FileChange[]

List of all files that were modified during patching

Show FileChange properties

string

Path to the file that was changed (relative to cwd)

string

Detailed description of the changes made to the file

string

Suggested title for the pull request

string

Detailed description for the pull request, including:

Summary of the vulnerability
Changes made
Testing performed
Remediation approach

Usage Examples

import { runPatchingAgent } from '@pensar/apex/api/patching';
import { createSession } from '@pensar/apex/session';

const session = await createSession({
  name: 'Patch SQLi',
  targets: [],
});

const result = await runPatchingAgent({
  cwd: '/home/user/projects/my-app',
  vulnerability: {
    name: 'SQL Injection in User Search',
    severity: 'HIGH',
    description: 'User input from search parameter is directly ' +
                 'concatenated into SQL query without sanitization',
    location: 'src/controllers/userController.ts',
    startLineNumber: 42,
    endLineNumber: 45,
    cweMapping: ['CWE-89'],
  },
  model: 'claude-sonnet-4-20250514',
  session,
});

console.log(`Patched ${result.filesChanged.length} files:`);
result.filesChanged.forEach((file) => {
  console.log(`  ${file.filePath}: ${file.changesDescription}`);
});

console.log(`\nPR Title: ${result.prTitle}`);
console.log(`\nPR Description:\n${result.prDescription}`);

import { runPatchingAgent } from '@pensar/apex/api/patching';
import { createSession } from '@pensar/apex/session';

const session = await createSession({
  name: 'Monitored Patch',
  targets: [],
});

const result = await runPatchingAgent({
  cwd: '/path/to/project',
  vulnerability: {
    name: 'XSS in Comment Rendering',
    severity: 'CRITICAL',
    description: 'User-generated content is rendered without HTML escaping',
    location: 'src/components/Comment.tsx',
    startLineNumber: 23,
  },
  model: 'claude-sonnet-4-20250514',
  session,
  consumeCallbacks: {
    onTextDelta: (d) => process.stdout.write(d.text),
    
    onToolCall: (d) => {
      console.log(`\n→ ${d.toolName}`);
      if (d.toolName === 'update_file') {
        console.log(`  Patching: ${d.args.filePath}`);
      } else if (d.toolName === 'execute_command') {
        console.log(`  Running: ${d.args.command}`);
      }
    },
    
    onToolResult: (d) => {
      console.log(`✓ ${d.toolName}`);
    },
  },
});

console.log('\nPatch complete!');

import { runPatchingAgent } from '@pensar/apex/api/patching';
import { createSandbox } from '@pensar/apex/sandbox';
import { createSession } from '@pensar/apex/session';

const session = await createSession({
  name: 'Sandboxed Patch',
  targets: [],
});

// Create isolated sandbox with the project
const sandbox = await createSandbox({
  type: 'docker',
  image: 'node:18',
  workdir: '/app',
});

// Clone repo into sandbox
await sandbox.exec('git clone https://github.com/org/repo.git /app');
await sandbox.exec('cd /app && npm install');

try {
  // All file operations happen in sandbox
  const result = await runPatchingAgent({
    cwd: '/app',
    vulnerability: {
      name: 'Path Traversal in File Upload',
      severity: 'HIGH',
      description: 'Filename is not validated, allowing path traversal',
      location: 'src/routes/upload.ts',
    },
    model: 'claude-sonnet-4-20250514',
    session,
    sandbox,  // All tools execute in sandbox
  });
  
  // Extract patched files from sandbox
  for (const file of result.filesChanged) {
    const contents = await sandbox.readFile(file.filePath);
    // Process or commit the changes
  }
} finally {
  await sandbox.destroy();
}

import { runPatchingAgent } from '@pensar/apex/api/patching';
import { createSession } from '@pensar/apex/session';

const session = await createSession({
  name: 'Batch Patching',
  targets: [],
});

const vulnerabilities = [
  {
    name: 'SQL Injection in Users API',
    severity: 'HIGH',
    description: 'Unparameterized query in user search',
    location: 'src/api/users.ts',
    startLineNumber: 34,
  },
  {
    name: 'XSS in Profile Page',
    severity: 'MEDIUM',
    description: 'Unescaped user bio rendering',
    location: 'src/pages/profile.tsx',
    startLineNumber: 56,
  },
];

const allChanges = [];

for (const vuln of vulnerabilities) {
  console.log(`\nPatching: ${vuln.name}...`);
  
  const result = await runPatchingAgent({
    cwd: '/path/to/project',
    vulnerability: vuln,
    model: 'claude-sonnet-4-20250514',
    session,
  });
  
  allChanges.push(...result.filesChanged);
  console.log(`✓ Patched ${result.filesChanged.length} files`);
}

console.log(`\nTotal files changed: ${allChanges.length}`);

import { runPatchingAgent } from '@pensar/apex/api/patching';
import { readFileSync } from 'fs';
import { createSession } from '@pensar/apex/session';

const session = await createSession({
  name: 'Patch with PoC',
  targets: [],
});

// Load PoC script from finding
const pocPath = '/path/to/findings/sql-injection-poc.py';
const pocContents = readFileSync(pocPath, 'utf-8');

const result = await runPatchingAgent({
  cwd: '/path/to/project',
  vulnerability: {
    name: 'SQL Injection in Login',
    severity: 'CRITICAL',
    description: 'Username parameter is vulnerable to SQL injection',
    location: 'src/auth/login.ts',
    startLineNumber: 28,
    endLineNumber: 32,
    cweMapping: ['CWE-89'],
    // Include PoC for context
    poc: {
      fileName: 'sql-injection-poc.py',
      contents: pocContents,
    },
  },
  model: 'claude-sonnet-4-20250514',
  session,
});

console.log('Patch applied with PoC context');

Patching Capabilities

Code Analysis

The patching agent can:

Read and understand complex codebases
Trace dataflow through functions and modules
Identify input validation gaps
Understand framework-specific patterns
Analyze dependencies and imports

Patch Generation

Supported remediation patterns:

Input validation: Add sanitization and validation
Parameterized queries: Convert to prepared statements
Output encoding: Add HTML/URL/SQL escaping
Access control: Add authorization checks
Cryptographic fixes: Upgrade weak algorithms
Configuration hardening: Fix insecure defaults

Verification

After patching, the agent:

Runs linters to ensure code quality
Executes type checkers (TypeScript, mypy, etc.)
Runs existing test suites
Verifies the vulnerability is resolved
Ensures no regressions introduced

Best Practices

Provide Detailed Context

More context leads to better patches:

Include precise line numbers
Provide CWE mappings
Include PoC scripts when available
Add dataflow analysis if available

Review Generated Patches

Always review patches before merging:

Verify the fix addresses the root cause
Check for edge cases
Ensure coding standards are met
Validate test coverage

Use Sandboxes for Safety

For untrusted codebases:

Always use sandbox isolation
Never patch production code directly
Test patches in staging first

Blackbox Pentest

Discover vulnerabilities to patch

Targeted Pentest

Find specific vulnerabilities

API Overview

Core APIs

Agents

Overview

runPatchingAgent

Parameters

Response

Usage Examples

Patching Capabilities

Code Analysis

Patch Generation

Verification

Best Practices

Provide Detailed Context

Review Generated Patches

Use Sandboxes for Safety

Blackbox Pentest

Targeted Pentest

​Overview

​runPatchingAgent

​Parameters

​Response

​Usage Examples

​Patching Capabilities

​Code Analysis

​Patch Generation

​Verification

​Best Practices

​Provide Detailed Context

​Review Generated Patches

​Use Sandboxes for Safety

​Related APIs

Blackbox Pentest

Targeted Pentest

Overview

runPatchingAgent

Parameters

Response

Usage Examples

Patching Capabilities

Code Analysis

Patch Generation

Verification

Best Practices

Provide Detailed Context

Review Generated Patches

Use Sandboxes for Safety

Related APIs