Skip to content
  • faq

Frequently Asked Questions

General Questions

Section titled “General Questions”

What is SPEAR and who is it for?

Section titled “What is SPEAR and who is it for?”

SPEAR (Security Posture Evaluation And Response) is a comprehensive security assessment management platform designed for penetration testing firms, security consultants, and internal security teams. It streamlines the entire security assessment lifecycle from client engagement through final report delivery.

What makes SPEAR different from other security assessment platforms?

Section titled “What makes SPEAR different from other security assessment platforms?”

SPEAR provides an integrated workflow covering:

  • Sales & Scoping: Client management, scoping workbench, and public approval portals
  • Project Management: Scheduling, resource allocation, and status tracking
  • Operations: Asset management, vulnerability tracking, and physical security assessments
  • Reporting: Real-time collaborative editing, findings library, and branded PDF/DOCX export
  • Administration: RBAC, OAuth/SSO, branding customization, and audit logging

The platform is self-hosted, giving you complete control over your sensitive assessment data.

What are the system requirements?

Section titled “What are the system requirements?”

Minimum Requirements:

  • Operating System: Linux, Windows 10+, or macOS 11+
  • Architecture: amd64 or arm64
  • RAM: 2GB minimum, 4GB recommended
  • Disk: 1GB for application, additional space for data storage
  • Network: Port 8090 (configurable)

Installation & Setup

Section titled “Installation & Setup”

How do I install SPEAR?

Section titled “How do I install SPEAR?”
  1. Download the latest release for your platform from the releases page
  2. Extract the archive
  3. Set the SPEAR_ENCRYPTION_KEY environment variable
  4. Run ./spear serve

See the Downloads page for detailed platform-specific instructions.

What is the SPEAR_ENCRYPTION_KEY and how do I generate it?

Section titled “What is the SPEAR_ENCRYPTION_KEY and how do I generate it?”

The SPEAR_ENCRYPTION_KEY is a 32-character encryption key used to protect sensitive data stored in the database. Generate one using:

Terminal window
# Linux/macOS
openssl rand -base64 32 | head -c 32


# Or use any secure password generator

Store this key securely - losing it means losing access to encrypted data.

Can SPEAR run on Windows/macOS/Linux?

Section titled “Can SPEAR run on Windows/macOS/Linux?”

Yes, SPEAR provides pre-built binaries for:

  • Linux (amd64, arm64)
  • Windows (amd64, arm64)
  • macOS (amd64, arm64 - Apple Silicon)

How do I set up SSL with Traefik?

Section titled “How do I set up SSL with Traefik?”

See the Traefik SSL deployment guide for step-by-step instructions on configuring automatic SSL certificates with Let’s Encrypt.

Features & Capabilities

Section titled “Features & Capabilities”

What scanner formats can SPEAR import?

Section titled “What scanner formats can SPEAR import?”

SPEAR supports importing findings from multiple security tools:

  • Burp Suite: XML export format
  • NodeZero: JSON export format
  • Nexpose/InsightVM: XML export format
  • BloodHound: JSON export format
  • Atlas: Native format migration

How does real-time collaboration work?

Section titled “How does real-time collaboration work?”

SPEAR uses Y.js-powered real-time collaboration that allows multiple team members to:

  • Edit report sections simultaneously
  • See each other’s cursors and selections
  • Resolve conflicts automatically
  • Work offline with automatic sync when reconnected

Can I customize report branding?

Section titled “Can I customize report branding?”

Yes, the Admin module provides comprehensive branding controls:

  • Logo upload (light and dark variants)
  • Color scheme customization
  • Font selection
  • Cover page templates
  • Header/footer configuration
  • Custom CSS for PDF exports

What AI features are available?

Section titled “What AI features are available?”

With OpenAI integration configured, SPEAR provides:

  • AI-assisted finding descriptions
  • Remediation recommendation generation
  • Executive summary drafting
  • Technical writing assistance

User Management

Section titled “User Management”

How do I create users and assign permissions?

Section titled “How do I create users and assign permissions?”
  1. Navigate to Admin > Users & Access
  2. Click Create User
  3. Fill in user details (name, email, password)
  4. Assign the user to one or more Groups
  5. Groups determine the user’s permissions through assigned Roles

What’s the difference between groups and roles?

Section titled “What’s the difference between groups and roles?”
  • Roles: Define permission sets (what actions can be performed)
  • Groups: Collections of users that share the same roles

This separation allows flexible permission management - you can create roles like “Report Editor” or “Project Manager” and assign them to groups like “Senior Consultants” or “Interns”.

Can SPEAR integrate with SSO/OAuth?

Section titled “Can SPEAR integrate with SSO/OAuth?”

Yes, SPEAR supports OAuth2/OpenID Connect integration with providers including:

  • Google Workspace
  • Microsoft Azure AD / Entra ID
  • GitHub
  • GitLab
  • Okta
  • Custom OIDC providers

Configure these in Admin > Authentication.

Data & Security

Section titled “Data & Security”

Where is data stored?

Section titled “Where is data stored?”

SPEAR uses an embedded SQLite database stored locally. Default location:

  • Linux: ./pb_data/
  • Windows: .\pb_data\

Uploaded files (images, attachments) are stored in ./pb_data/storage/.

Is data encrypted?

Section titled “Is data encrypted?”
  • At rest: Sensitive fields are encrypted using the SPEAR_ENCRYPTION_KEY
  • In transit: Use HTTPS in production (see Traefik SSL deployment)
  • Backups: Can be encrypted when using S3-compatible storage with server-side encryption

How do backups work?

Section titled “How do backups work?”

SPEAR provides automated backup scheduling:

  1. Configure backup settings in Admin > System > Backups
  2. Set schedule (daily, weekly, custom cron)
  3. Optionally configure S3-compatible storage destination
  4. Backups include database and uploaded files

Manual backups can be triggered anytime from the admin interface.

What audit logging is available?

Section titled “What audit logging is available?”

SPEAR logs security-relevant events including:

  • User authentication (login/logout/failures)
  • Permission changes
  • Record modifications
  • Export operations
  • Administrative actions

View logs in Admin > Security > Audit Log.

Integrations

Section titled “Integrations”

What third-party services does SPEAR integrate with?

Section titled “What third-party services does SPEAR integrate with?”
  • OpenAI: AI writing assistance
  • S3-Compatible Storage: Backups to AWS S3, MinIO, Backblaze B2, etc.
  • SMTP: Email notifications
  • OAuth Providers: SSO authentication

How do I configure OpenAI integration?

Section titled “How do I configure OpenAI integration?”
  1. Navigate to Admin > Integrations
  2. Enter your OpenAI API key
  3. Select the model (GPT-4 recommended)
  4. Configure rate limits if desired
  5. Save and test the connection

Can I use S3-compatible storage for backups?

Section titled “Can I use S3-compatible storage for backups?”

Yes, SPEAR supports any S3-compatible storage provider:

  • AWS S3
  • MinIO (self-hosted)
  • Backblaze B2
  • DigitalOcean Spaces
  • Cloudflare R2

Configure in Admin > System > Backups > Remote Storage.

Troubleshooting

Section titled “Troubleshooting”

How do I view application logs?

Section titled “How do I view application logs?”

Console logs:

Terminal window
./spear serve 2>&1 | tee spear.log

Structured logs: Access the admin panel at /_/ and navigate to Logs.

What should I do if the service won’t start?

Section titled “What should I do if the service won’t start?”

  1. Check port availability: Ensure port 8090 isn’t in use

    Terminal window
    lsof -i :8090  # Linux/macOS
    netstat -an | findstr 8090  # Windows

  2. Verify encryption key: Ensure SPEAR_ENCRYPTION_KEY is set and 32 characters

  3. Check permissions: Ensure write access to the pb_data directory

  4. Review logs: Run with verbose output

    Terminal window
    ./spear serve --debug

How do I reset the admin password?

Section titled “How do I reset the admin password?”

Access the PocketBase admin panel directly:

  1. Navigate to http://localhost:8090/_/
  2. Click “Forgot Password” if configured with SMTP
  3. Or access the database directly and update the password hash

For initial setup, create the first admin account at http://localhost:8090/_/.

Getting Help

Section titled “Getting Help”

If your question isn’t answered here:

  1. Check the documentation
  2. Search existing GitHub issues
  3. Open a new issue with details about your problem
  4. Contact support at [email protected]