PentestKit NPM Package

PentestKit (pentestkit) runs PTK-backed browser security automation from a normal Node project. It bundles the PTK browser extension artifacts and exposes command-line tools for one-command scans, deterministic crawling, scenario-guided exploration, CI validation, and optional tool-server workflows.

Use this documentation when you installed PTK from npm. If you cloned the repository and want to run SDK source files directly, use pentestkit/sdks/README.md instead.

Install

npm install -D pentestkit
npx playwright install chromium

If the first browser launch after install times out, retry once with --browser-launch-timeout-ms 60000. See troubleshooting.

The package includes:

• ptk-scan: product scan command for most users
• ptk-agent: lower-level scan, crawl, config, module, benchmark, and compare commands
• ptk-agent-mcp-server: optional MCP/tool server surface
• bundled Chromium unpacked extension at extensions/chromium-unpacked
• bundled CRX and XPI artifacts for prepared-profile workflows
• Cypress integration via require("pentestkit/cypress")
• Playwright Python and Selenium Python SDK source and examples

First Check

Verify that the installed package can resolve the bundled extension:

npx ptk-agent --doctor-extension

Expected result:

{
  "source": "bundled-package"
}

If the source is not bundled-package, check whether PTK_EXTENSION_DIR, PTK_EXTENSION_PATH, or a config file is overriding extension resolution.

Which Command Should I Use?

Use ptk-scan for normal scans. It is the product-level command for local testing and CI:

npx ptk-scan https://target.example \
  --engine DAST,IAST \
  --max-routes 100 \
  --output-dir .ptk/artifacts

Use ptk-agent when you need lower-level tooling around the scan runner:

npx ptk-agent validate-config --config ptk.config.json --json
npx ptk-agent scan --config ptk.config.json
npx ptk-agent modules list
npx ptk-agent compare --baseline-artifact before.json --candidate-artifact after.json
npx ptk-agent --doctor-extension

| Command | Use it for | Typical input | | --- | --- | --- | | ptk-scan | Day-to-day security scans and CI scan jobs. | URL or config plus scan flags. | | ptk-agent scan | Reproducible config-owned scan jobs. | ptk.config.json. | | ptk-agent validate-config | Checking config before a browser launches. | ptk.config.json. | | ptk-agent --doctor-extension | Debugging extension resolution. | No target needed. | | ptk-agent modules | Inspecting available module packs. | Optional config. | | ptk-agent compare | Comparing saved artifacts in CI. | Existing artifact files. | | ptk-agent benchmark | PTK development and release validation. | Benchmark targets. | | ptk-agent-mcp-server | Connecting PTK to an MCP-capable tool host. | MCP stdio or registry inspection. |

If you are unsure, start with ptk-scan. Move to ptk-agent scan --config ptk.config.json when the command should be owned by a committed CI config file.

Quick Scan

With no --engine flag, ptk-scan enables the default browser engines only. Pass --engine DAST,IAST,SAST,SCA when you want all engines enabled.

Run a bounded DAST scan against an authorized target:

npx ptk-scan https://target.example \
  --engine DAST \
  --max-routes 50 \
  --max-actions-per-route 1 \
  --output-dir .ptk/artifacts/quick-scan

Run a broader PTK-backed browser scan:

npx ptk-scan https://target.example \
  --engine DAST,IAST \
  --require-ptk-bridge \
  --require-ptk-findings-export \
  --wait-for-ptk-complete \
  --ptk-drain-timeout-ms 120000 \
  --max-routes 100 \
  --output-dir .ptk/artifacts/ptk-scan

Use --require-ptk-bridge when the run must fail if the PTK extension bridge is unavailable. Use --require-ptk-findings-export when CI must fail if the final findings export cannot be retrieved.

Authenticated Scan

Pass credentials through environment variables so secrets do not appear in shell history:

export PTK_SCAN_USERNAME='[email protected]'
export PTK_SCAN_PASSWORD='change-me'

npx ptk-scan https://target.example \
  --engine DAST,IAST \
  --username-env PTK_SCAN_USERNAME \
  --password-env PTK_SCAN_PASSWORD \
  --include-secrets \
  --max-routes 100 \
  --output-dir .ptk/artifacts/credential-aware-crawl

--include-secrets allows local browser execution to use supplied credentials. PTK artifacts and agent/provider prompts stay redacted by default.

This is credential-aware crawl, not automatic login. Credentials alone do not log in. They are values that scenario/auth/form steps can use. A plain crawl keeps crawler.forms.allowAuth=false by default, so login forms are discovered but not submitted. For authenticated Juice Shop-style flows, use a scenario.

Scenario-Guided Scan

Scenarios can be markdown or JSON. Markdown is intended for normal users:

cat > ptk-scenario.md <<'EOF'
Log in with the provided credentials.
Search for "apple".
Add one visible product to the basket.
Open the basket.
Do not checkout or pay.
EOF

npx ptk-scan https://target.example \
  --engine DAST,IAST,SAST,SCA \
  --scenario ptk-scenario.md \
  --username-env PTK_SCAN_USERNAME \
  --password-env PTK_SCAN_PASSWORD \
  --include-secrets \
  --require-ptk-bridge \
  --require-ptk-findings-export \
  --wait-for-ptk-complete \
  --ptk-drain-timeout-ms 120000 \
  --max-routes 120 \
  --output-dir .ptk/artifacts/scenario

Scenario guidance does not expand scope or disable safety checks. Use --aggressive only when state-changing interactions are acceptable on the target.

CI/CD Usage

For CI, commit a ptk.config.json, keep secrets in CI variables, and validate the config before the scan:

{
  "version": "ptk-agent-v2-config",
  "target": {
    "baseUrl": "https://staging.example.test"
  },
  "scenario": {
    "enabled": true,
    "file": "ptk-scenario.md"
  },
  "engines": {
    "dast": { "enabled": true, "modulePacks": ["free"] },
    "iast": { "enabled": true, "modulePacks": ["free"] },
    "sast": { "enabled": false, "modulePacks": ["free"] },
    "sca": { "enabled": false, "modulePacks": [] }
  },
  "ptk": {
    "requireBridge": true,
    "requireFindingsExport": true,
    "drainMode": "until-complete",
    "drainTimeoutMs": 120000
  },
  "crawler": {
    "maxRoutes": 100
  },
  "artifacts": {
    "outputDir": ".ptk/artifacts"
  }
}

Example CI steps:

npm ci
npx playwright install chromium
npx ptk-agent validate-config --config ptk.config.json --json
npx ptk-scan --config ptk.config.json \
  --username-env PTK_SCAN_USERNAME \
  --password-env PTK_SCAN_PASSWORD \
  --include-secrets

Use --require-ptk-bridge and --require-ptk-findings-export for CI gates where a missing extension or failed findings export should fail the job. Store .ptk/artifacts as a CI artifact, but do not commit it.

Command Overview

npx ptk-scan --help
npx ptk-agent --help
npx ptk-agent-mcp-server --help

Common commands:

npx ptk-scan https://target.example
npx ptk-agent crawl --url https://target.example
npx ptk-agent scan --config ptk.config.json
npx ptk-agent validate-config --config ptk.config.json --json
npx ptk-agent modules list
npx ptk-agent compare --baseline-artifact before.json --candidate-artifact after.json
npx ptk-agent benchmark --targets juice-shop --scenario-mode explicit
npx ptk-agent-mcp-server --stdio
npx ptk-agent-mcp-server --list-tools

See CLI reference for the full command surface. See configuration files for ptk.config.json structure and examples. See MCP server for MCP client configuration and safety controls.

Extension Loading

For npm installs, Chromium-family scans use the bundled unpacked extension by default. Override only when needed:

PTK_EXTENSION_DIR=/absolute/path/to/unpacked-extension \
npx ptk-agent --doctor-extension

Resolution order:

1. explicit CLI/config extension path
2. PTK_EXTENSION_DIR
3. PTK_EXTENSION_PATH
4. bundled package extension
5. local-dev fallback only when explicitly allowed in source-tree workflows

See extension loading.

Framework Integrations

Cypress:

const path = require("path");
const { defineConfig } = require("cypress");
const { ptkPlugin } = require("pentestkit/cypress");
const ptkPackageRoot = path.dirname(require.resolve("pentestkit/package.json"));

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      ptkPlugin(on, config);
      return config;
    }
  },
  env: {
    PTK_EXTENSION_PATH: path.join(ptkPackageRoot, "extensions", "chromium-unpacked")
  }
});

Playwright Python and Selenium Python SDKs are included in the npm tarball as SDK source and examples. Install their Python dependencies from the included Python package directories when using them in Python projects.

See framework integrations.

Outputs

By default, scan artifacts are written under .ptk/artifacts or the path passed to --output-dir.

Important artifacts include:

• coverage.json: routes, endpoints, forms, and observed surfaces
• crawl-events.jsonl: route/action/event timeline
• ptk-lifecycle.json: PTK start, status, drain, stop, and export lifecycle
• ptk-lifecycle-normalized.json: normalized export and engine readiness truth
• findings.json or exported PTK report artifacts when findings export is available
• scenario-result.json when a scenario ran

Do not commit .ptk/, browser profiles, cookies, trace files, screenshots, or sensitive replay bundles.

Replayable Exports

Normal page-facing exports are evidence-only and redacted. Replayable exports can include cookies, auth headers, CSRF tokens, and request bodies, so they require an explicit privileged SDK transport and a local output path. Agents and provider prompts never receive replayable secret-bearing exports.

See the Playwright Python and Selenium Python docs for replayable export examples.

Documentation

• CLI reference
• Configuration files
• MCP server
• Extension loading
• Authenticated scans
• Scenario-guided scans
• Framework integrations
• Troubleshooting

Safety

Run PTK only against systems you own or have explicit permission to test. Start with low route/action budgets in new environments, review output artifacts, then increase budgets as needed.