Skip to main content

​
Quickstart Guide

This guide will take you from zero to your first security assessment in Faction. We’ll use Docker Compose for the fastest setup experience.
This quickstart uses Docker Compose to deploy Faction with all dependencies. For detailed installation options and configuration, see the Installation Guide.

​
Prerequisites

Before starting, ensure you have:
  • Docker and Docker Compose installed
  • Git for cloning the repository
  • MongoDB-compatible CPU with AVX support (see troubleshooting if using VirtualBox or Kubernetes)

​
Step 1: Clone and Start Faction

1

Clone the Repository

Clone the Faction repository from GitHub:
git clone https://github.com/factionsecurity/faction.git
cd faction
2

Launch with Docker Compose

Build and start the Faction containers:
docker-compose up --build
The first build will take several minutes as it downloads dependencies and builds the WAR file. Subsequent starts will be much faster.
Wait for the containers to fully start. You’ll see output indicating Tomcat has started successfully.
3

Access Faction

Once the containers are running, navigate to:
http://127.0.0.1:8080
You should see the Faction login page.

​
Step 2: Create Admin Account

On first boot, Faction will prompt you to create an administrator account.
1

Fill in Admin Details

On the initial setup page, provide:
  • Username - Your admin username
  • Email Address - Admin email for notifications
  • Password - Strong password for the admin account
  • Confirm Password - Re-enter your password
2

Complete Registration

Click Create Account to finalize the admin user.
Store your admin credentials securely. This account has full access to all Faction features and assessments.
3

Log In

After account creation, log in with your new credentials.

​
Step 3: Import Vulnerability Templates

Faction includes over 75 prepopulated vulnerability templates to accelerate your reporting.
1

Navigate to Templates

From the main dashboard, go to:Templates → Default Vulnerabilities
2

Update from Faction

Click the Update from Faction button.This will download the latest vulnerability templates from the Faction repository, including common findings for:
  • SQL Injection
  • Cross-Site Scripting (XSS)
  • Authentication Bypasses
  • Authorization Issues
  • And many more…
3

Verify Import

Once complete, you’ll see the vulnerability templates populated in your library. You can now use these templates when creating findings in assessments.
You can customize these templates or create your own to match your organization’s reporting style.

​
Step 4: Create Your First Assessment

Now let’s create your first security assessment project.
1

Create New Assessment

From the dashboard, click New Assessment or navigate to:Assessments → Create Assessment
2

Fill in Assessment Details

Provide the assessment information:
  • Assessment Name - e.g., “Web Application Penetration Test”
  • Client/Organization - The target organization
  • Assessment Type - Select the type (Web App, Network, API, etc.)
  • Start Date - When testing begins
  • End Date - Target completion date
  • Team Members - Assign assessors to the project
3

Configure Assessment Settings

Set additional parameters:
  • Report Template - Choose your DOCX template
  • Peer Review - Enable if you want peer review workflow
  • SLA Settings - Configure remediation tracking alerts
4

Save and Start Testing

Click Create Assessment to finalize.Your assessment is now ready! You can:
  • Add findings from vulnerability templates
  • Use the Burp Suite extension to import findings
  • Collaborate with team members in real-time
  • Generate reports at any time

​
Step 5: Add Your First Finding

1

Open the Assessment

Click on your newly created assessment from the dashboard.
2

Add Finding

Click Add Finding or New Vulnerability.
3

Select Template

Choose a vulnerability template from your imported library, or create a custom finding.Fill in the specific details:
  • Affected URLs/components
  • Severity rating
  • Proof of concept
  • Remediation guidance
4

Save Finding

Click Save to add the finding to your assessment.
You can add screenshots, code snippets, and detailed technical information to each finding.

​
Step 6: Generate Your First Report

1

Navigate to Report Generation

From your assessment, click Generate Report or go to:Reports → Generate
2

Select Report Template

Choose your report template (DOCX format).You can customize templates to match your organization’s branding and format requirements.
3

Generate and Download

Click Generate and wait for the report to compile.Once complete, download your professional DOCX report containing all findings, executive summaries, and technical details.

​
Next Steps

Burp Suite Integration

Install the Faction Burp extension to send findings directly from Burp Suite.

Custom Report Templates

Learn how to create custom DOCX templates for your organization.

API Integration

Explore the REST API to integrate Faction with your existing tools.

App Store Extensions

Add functionality with extensions like Jira integration and custom charts.

​
Common Next Steps

​
Configure Email Notifications

Set up SMTP to receive alerts for:
  • Assessment deadlines
  • Remediation SLA warnings
  • Peer review requests
  • Retest scheduling
Navigate to Settings → Email Configuration to configure SMTP settings.

​
Set Up Team Members

Add additional users to your Faction instance:
  1. Go to Users → Create User
  2. Assign appropriate roles (Admin, Assessor, Viewer)
  3. Set up LDAP/OAuth if using enterprise authentication

​
Configure Remediation Tracking

Set up SLA alerts for vulnerability remediation:
  1. Go to Settings → Remediation SLA
  2. Configure timeframes for each severity level:
    • Critical: 30 days (default)
    • High: 70 days (default)
    • Medium: Configurable
    • Low: Configurable

​
Getting Help

Need assistance? Join the #project-faction channel on OWASP Slack or check out the Faction YouTube channel for video tutorials.

​
Video Tutorials

For visual walkthroughs of these steps, visit the Faction YouTube Channel where you can see Faction in action.
Congratulations! You’ve successfully set up Faction and created your first assessment. You’re now ready to streamline your penetration testing workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us