pensar swarm

Run parallel penetration tests on multiple targets simultaneously

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

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

Multi-Tenant

Test multiple tenant environments:

tenants.json

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

pensar swarm tenants.json

Staging Environments

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

Bug Bounty

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:

1. Reduce target count - Test fewer targets per swarm
2. Upgrade API plan - Increase rate limits with provider
3. Use multiple API keys - Distribute across keys (requires code modification)
4. 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