Integrations

SPEAR integrates with third-party services to enhance functionality. Configure API connections, AI services, and other integrations from the administration panel.

---

Available Integrations

Integration	Purpose	Status
OpenAI	AI writing assistance	Optional
Anthropic	AI writing assistance	Optional
Webhooks	Event notifications	Optional
API Access	External automation	Built-in

---

OpenAI Integration

Enable AI-powered writing assistance for report creation and finding descriptions.

🖥️ OpenAI Integration Configuration Screenshot

Configuration

Navigate to Admin > Integrations > OpenAI

Setting	Description
API Key	Your OpenAI API key
Model	GPT model to use (gpt-4, gpt-4-turbo, gpt-3.5-turbo)
Max Tokens	Maximum response length
Temperature	Creativity level (0-1)
Rate Limit	Requests per minute limit

Setup Steps

1. Create an account at OpenAI
2. Generate an API key from the API keys page
3. Enter the API key in SPEAR
4. Select your preferred model
5. Test the connection
6. Save configuration

Model Selection

Model	Best For	Cost
GPT-4	High-quality technical writing	Higher
GPT-4 Turbo	Balance of quality and speed	Medium
GPT-3.5 Turbo	Fast responses, simpler tasks	Lower

AI Features

Once configured, AI assistance is available for:

• Finding Descriptions: Generate detailed vulnerability descriptions
• Remediation Steps: Create remediation recommendations
• Executive Summaries: Draft executive summary content
• Technical Writing: Improve technical documentation

Usage

In the report editor:

1. Position cursor where you want AI content
2. Click the AI assist button or use keyboard shortcut
3. Select the type of assistance
4. Review and edit generated content
5. Insert into document

---

Anthropic Integration

Alternative AI provider using Claude models.

🖥️ Anthropic Integration Settings Screenshot

Configuration

Navigate to Admin > Integrations > Anthropic

Setting	Description
API Key	Your Anthropic API key
Model	Claude model to use
Max Tokens	Maximum response length

Setup

1. Create an account at Anthropic
2. Generate an API key
3. Enter the API key in SPEAR
4. Configure model preferences
5. Test and save

---

Webhook Configuration

🖥️ Webhook Configuration Interface Screenshot

Send event notifications to external services.

Event Types

Event	Trigger
report.created	New report created
report.exported	Report exported to PDF
report.shared	Report shared via portal
finding.created	New finding added
project.status_changed	Project status updated
user.login	User login event

Creating a Webhook

1. Navigate to Admin > Integrations > Webhooks
2. Click Add Webhook
3. Configure:
   • Name: Descriptive name
   • URL: Endpoint to receive events
   • Events: Which events to send
   • Secret: Shared secret for verification
4. Test the webhook
5. Enable and save

Webhook Payload

{
  "event": "report.exported",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "report_id": "abc123",
    "report_title": "Security Assessment Report",
    "exported_by": "user@example.com",
    "format": "pdf"
  },
  "signature": "sha256=..."
}

Verifying Webhooks

Verify webhook authenticity using the signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

---

API Access

🖥️ API Access Management Screenshot

SPEAR provides a REST API for external integrations.

API Documentation

Access interactive API documentation at:

https://your-spear-instance/api/docs

Authentication

API requests use bearer token authentication:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://your-spear-instance/api/collections/reports/records

Generating API Tokens

1. Go to Account Settings > API Tokens
2. Click Generate New Token
3. Set token name and expiration
4. Copy the token (shown only once)
5. Store securely

Rate Limiting

Default API rate limits:

Endpoint Type	Limit
Read operations	100/minute
Write operations	30/minute
Export operations	10/minute

Configure custom limits at Admin > Integrations > API.

---

Scanner Integrations

Import findings from security scanning tools.

Supported Formats

Scanner	Format	Notes
Burp Suite	XML	Professional/Enterprise export
NodeZero	JSON	API export
Nexpose/InsightVM	XML	Standard export
BloodHound	JSON	SharpHound collection
Atlas	JSON	Native format

Import Process

1. Export findings from your scanner
2. Navigate to Operations > Vulnerabilities > Import
3. Select scanner format
4. Upload the export file
5. Map fields if prompted
6. Review and confirm import

Automation

Automate scanner imports via API:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@burp-export.xml" \
  -F "format=burp" \
  https://your-spear-instance/api/imports/scanner

---

Custom Integrations

Integration API

Build custom integrations using the SPEAR API:

// Example: Create a finding via API
const response = await fetch('https://spear/api/collections/findings/records', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'SQL Injection',
    severity: 'high',
    description: '...',
    remediation: '...'
  })
});

Event Subscriptions

Subscribe to real-time events via WebSocket:

const ws = new WebSocket('wss://spear/api/realtime');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    collection: 'reports',
    token: 'YOUR_TOKEN'
  }));
};

---

Best Practices

API Keys

• Use separate keys for different integrations
• Set appropriate expiration dates
• Rotate keys regularly
• Never expose keys in client-side code

Webhooks

• Use HTTPS endpoints only
• Always verify signatures
• Handle retries idempotently
• Log webhook events for debugging

AI Integration

• Set reasonable rate limits
• Monitor API costs
• Review AI-generated content before publishing
• Provide clear prompts for better results

---

Troubleshooting

OpenAI Connection Failed

1. Verify API key is valid
2. Check for billing/quota issues
3. Ensure network allows outbound HTTPS
4. Try a different model

Webhook Not Received

1. Verify endpoint URL is correct
2. Check endpoint returns 2xx status
3. Review webhook logs in SPEAR
4. Test endpoint independently

API Rate Limited

1. Reduce request frequency
2. Implement exponential backoff
3. Cache responses where possible
4. Request rate limit increase if needed