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

Create an account at OpenAI
Generate an API key from the API keys page
Enter the API key in SPEAR
Select your preferred model
Test the connection
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:

Position cursor where you want AI content
Click the AI assist button or use keyboard shortcut
Select the type of assistance
Review and edit generated content
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

Create an account at Anthropic
Generate an API key
Enter the API key in SPEAR
Configure model preferences
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

Navigate to Admin > Integrations > Webhooks
Click Add Webhook
Configure:
- Name: Descriptive name
- URL: Endpoint to receive events
- Events: Which events to send
- Secret: Shared secret for verification
Test the webhook
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": "[email protected]",
    "format": "pdf"
  },
  "signature": "sha256=..."
}

Verifying Webhooks

Verify webhook authenticity by comparing the signature header with an HMAC-SHA256 hash of the payload using your shared secret. Most programming languages have built-in libraries for this verification.

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

Go to Account Settings > API Tokens
Click Generate New Token
Set token name and expiration
Copy the token (shown only once)
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

Export findings from your scanner
Navigate to Operations > Vulnerabilities > Import
Select scanner format
Upload the export file
Map fields if prompted
Review and confirm import

Automation

Scanner imports can be automated via the SPEAR API. Use the interactive API documentation at your SPEAR instance for endpoint details and examples.

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

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

Webhook Not Received

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

API Rate Limited

Reduce request frequency
Implement exponential backoff
Cache responses where possible
Request rate limit increase if needed