pensar swarm

The pensar swarm command orchestrates parallel pentests across multiple targets, enabling efficient large-scale security testing.

Synopsis

pensar swarm <targets> [options]

Description

Swarm mode allows you to:

Test multiple targets simultaneously
Scale security testing across infrastructure
Compare security posture across services
Efficiently audit microservice architectures

Swarm mode runs pentests in parallel. Ensure you have adequate API rate limits and system resources.

Arguments

targets

string

required

JSON string or path to JSON file containing target list.As JSON string:

pensar swarm '["https://api.example.com", "https://admin.example.com"]'

As file path:

pensar swarm targets.json

Targets File Format

Create a JSON file with target configurations:

targets.json

[
  {
    "url": "https://api.example.com",
    "name": "API Service",
    "priority": "high"
  },
  {
    "url": "https://admin.example.com",
    "name": "Admin Portal",
    "priority": "high"
  },
  {
    "url": "https://blog.example.com",
    "name": "Blog",
    "priority": "low"
  }
]

Or simple string array:

targets-simple.json

[
  "https://api.example.com",
  "https://admin.example.com",
  "https://blog.example.com"
]

Options

--model

string

default:"claude-sonnet-4-5"

AI model to use for all pentests.

pensar swarm targets.json --model claude-opus-4

All targets will use the same model.

--headers

string

default:"default"

Header mode for requests.Values:

none - No custom headers
default - Add User-Agent: pensar-apex
custom - Use custom headers defined with --header

pensar swarm targets.json --headers custom

--header

string

Add custom header to all requests (requires --headers custom).

pensar swarm targets.json \
  --headers custom \
  --header "User-Agent: security-scanner" \
  --header "X-Scanner-ID: swarm-001"

Can be specified multiple times.

Examples

Basic Swarm Test

Test multiple microservices:

pensar swarm '["https://api.example.com", "https://auth.example.com", "https://data.example.com"]'

Example Output

==========================================================
SWARM PENTEST
==========================================================
Targets: 3
Model:   claude-sonnet-4-5

[1/3] Testing api.example.com...
[2/3] Testing auth.example.com...
[3/3] Testing data.example.com...

→ All tests running in parallel...

✓ api.example.com complete    (5 findings)
✓ auth.example.com complete   (2 findings)
✓ data.example.com complete   (8 findings)

==========================================================
AGGREGATE RESULTS
==========================================================
Total Findings: 15
  CRITICAL: 3
  HIGH: 6
  MEDIUM: 4
  LOW: 2

Results:
  api.example.com:  ~/.pensar/sessions/swarm_abc/api/
  auth.example.com: ~/.pensar/sessions/swarm_abc/auth/
  data.example.com: ~/.pensar/sessions/swarm_abc/data/

Time: 12m 34s (parallel execution)

Using Targets File

Create targets.json:

[
  "https://staging-api.example.com",
  "https://staging-admin.example.com",
  "https://staging-web.example.com"
]

Run swarm:

pensar swarm targets.json

Custom Headers

Test with authentication:

pensar swarm targets.json \
  --headers custom \
  --header "Authorization: Bearer eyJ..." \
  --header "X-Tenant-ID: prod-001"

No Custom Headers

Disable all custom headers:

pensar swarm targets.json --headers none

Use Cases

Microservices
Multi-Tenant
Staging Environments
Bug Bounty

Test all services in a microservice architecture:

microservices.json

[
  "https://auth-service.internal",
  "https://user-service.internal",
  "https://payment-service.internal",
  "https://notification-service.internal",
  "https://api-gateway.internal"
]

pensar swarm microservices.json

Test multiple tenant environments:

tenants.json

[
  "https://tenant1.example.com",
  "https://tenant2.example.com",
  "https://tenant3.example.com"
]

pensar swarm tenants.json

Test all staging services before production:

staging.json

[
  "https://staging-api.example.com",
  "https://staging-web.example.com",
  "https://staging-admin.example.com"
]

pensar swarm staging.json --model claude-opus-4

Test all subdomains in scope:

# Discover subdomains (example with subfinder)
subfinder -d example.com -o subdomains.txt

# Convert to JSON
cat subdomains.txt | jq -R -s 'split("\n") | map(select(length > 0))' > targets.json

# Run swarm
pensar swarm targets.json

Performance Considerations

Parallelization

Swarm runs pentests in parallel:

3 targets = ~3x faster than sequential
10 targets = ~10x faster than sequential

Parallel execution is limited by:

AI provider rate limits
System CPU/memory
Network bandwidth

Rate Limiting

If you hit rate limits:

Reduce target count - Test fewer targets per swarm
Upgrade API plan - Increase rate limits with provider
Use multiple API keys - Distribute across keys (requires code modification)
Batch targets - Run multiple smaller swarms instead of one large one

Resource Usage

Each parallel pentest consumes:

Memory: ~500MB per target
CPU: ~25% per target
Network: ~10-20 MB/s per target

Testing 20+ targets simultaneously may require significant system resources.

Output Structure

Swarm creates a session per target:

~/.pensar/sessions/swarm_<timestamp>/
├── aggregate-report.md          # Combined report
├── aggregate-findings.json      # All findings
├── api.example.com/
│   ├── findings.json
│   ├── pocs/
│   └── report.md
├── auth.example.com/
│   ├── findings.json
│   ├── pocs/
│   └── report.md
└── data.example.com/
    ├── findings.json
    ├── pocs/
    └── report.md

Troubleshooting

Rate limit errors

Reduce parallel load:

# Split targets into smaller batches
# Batch 1
pensar swarm '["target1", "target2", "target3"]'

# Batch 2 (after first completes)
pensar swarm '["target4", "target5", "target6"]'

Or upgrade your AI provider plan for higher rate limits.

JSON parsing error

Verify JSON format:

# Test JSON validity
cat targets.json | jq .

Common issues:

Missing quotes around strings
Trailing commas
Unescaped quotes in URLs

Out of memory

Reduce target count:

# Instead of 20 targets at once
pensar swarm large-targets.json

# Split into batches of 5
pensar swarm batch-1.json  # 5 targets
pensar swarm batch-2.json  # 5 targets
pensar swarm batch-3.json  # 5 targets
pensar swarm batch-4.json  # 5 targets

Some targets fail

Check individual logs:

# View logs for specific target
cat ~/.pensar/sessions/swarm_abc/api.example.com/logs/*.log

Common causes:

Target unreachable
Authentication required
Rate limiting from target

Best Practices

Organize targets logically

Group related services:

# staging-services.json
["https://staging-api.example.com", ...]

# prod-services.json
["https://api.example.com", ...]

# internal-services.json
["https://auth.internal", ...]

Start with small batches

Test 2-3 targets first to validate:

# Test small batch
pensar swarm '["target1", "target2"]'

# If successful, scale up
pensar swarm all-targets.json

Use descriptive target names

Add metadata to targets:

[
  {
    "url": "https://api.example.com",
    "name": "Production API",
    "priority": "critical",
    "team": "platform"
  }
]

Makes results easier to triage.

Next Steps

Single Pentest

Run comprehensive test on one target

Quicktest

Rapid testing with specific objectives

CI/CD Integration

Automate swarm in pipelines

Sessions

Manage and review swarm results

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

Synopsis

Description

Arguments

Targets File Format

Options

Examples

Basic Swarm Test

Using Targets File

Custom Headers

No Custom Headers

Use Cases

Performance Considerations

Parallelization

Rate Limiting

Resource Usage

Output Structure

Troubleshooting

Best Practices

Next Steps

Single Pentest

Quicktest

CI/CD Integration

Sessions

Build docs developers (and LLMs) love

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

​Synopsis

​Description

​Arguments

​Targets File Format

​Options

​Examples

​Basic Swarm Test

​Using Targets File

​Custom Headers

​No Custom Headers

​Use Cases

​Performance Considerations

​Parallelization

​Rate Limiting

​Resource Usage

​Output Structure

​Troubleshooting

​Best Practices

​Next Steps

Single Pentest

Quicktest

CI/CD Integration

Sessions

Build docs developers (and LLMs) love

Synopsis

Description

Arguments

Targets File Format

Options

Examples

Basic Swarm Test

Using Targets File

Custom Headers

No Custom Headers

Use Cases

Performance Considerations

Parallelization

Rate Limiting

Resource Usage

Output Structure

Troubleshooting

Best Practices

Next Steps