First Steps¶

Now that you have installed Faraday, let's walk through the essential steps to get you up and running.

1. Access the Web UI¶

Open your browser and navigate to your Faraday instance:

Log in with the credentials generated during installation.

faraday-manage change-password

2. Create a Workspace¶

Faraday organizes all your security data into Workspaces. Each workspace represents a scope of work — a penetration test engagement, a regular scan cycle, an application assessment, or any logical grouping of assets and findings.

To create your first workspace:

1. Click the Faraday logo in the top-left corner
2. In the Workspaces tab, click + Add Workspace
3. Fill in the details:
   • Name — A short, descriptive name (e.g., external-pentest-q1)
   • Start/End Dates — Optional engagement dates
   • Description — Context about the scope
4. Click Create

3. Import Scan Data¶

The fastest way to populate your workspace is to import results from security tools you already use. Faraday supports 120+ tools including Nmap, Nessus, Burp Suite, OWASP ZAP, Nuclei, and many more.

Option A: Upload a Report File (Web UI)¶

1. Open your workspace
2. Go to Vulnerabilities
3. Click + Add Vulnerability
4. Click Import from file
5. Browse or drag-and-drop your report file (XML, JSON, CSV, or HTML depending on the tool)
6. Click Upload
7. Refresh the view to see imported findings

Faraday automatically detects the tool format and parses hosts, services, and vulnerabilities from the report.

Option B: Use the Faraday CLI¶

The Faraday CLI lets you import reports and run tools directly from your terminal:

# Install the CLI
pip3 install faraday-cli

# Authenticate with your Faraday server
faraday-cli auth

# Select your workspace
faraday-cli workspace select external-pentest-q1

# Import an Nmap report
faraday-cli report /path/to/nmap-scan.xml

# Or run a tool and auto-import results
faraday-cli tool run "nmap -sV -oX /tmp/nmap.xml 192.168.1.0/24"

Option C: Use Faraday Agents (Automated Scanning)¶

For recurring or automated scans, set up Faraday Agents. Agents run executors (Nmap, Nessus, Nuclei, etc.) on remote machines and push results directly into Faraday.

See the Agent Getting Started Guide for setup instructions.

Option D: Use the API¶

Faraday's REST API allows programmatic data import. Upload reports or create findings directly:

# Upload a report via API
curl -X POST "http://localhost:5985/_api/v3/ws/external-pentest-q1/upload_report" \
  -H "Authorization: Token <your-api-token>" \
  -F "file=@/path/to/report.xml"

See API Token for how to generate your token, and the API Reference for the full endpoint list.

4. Explore Your Results¶

Once data is imported, Faraday provides several views to analyze your findings:

Assets¶

Navigate to Assets to see all discovered hosts. Asset table includes these main fields for each asset:

• IP address and hostnames
• Open ports and detected services
• Associated vulnerability count
• Asset importance and risk score
• Graphical summary of important vulnerabilities of each asset

Services¶

Navigate to Services to see all discovered services in the discovered hosts. Each service shows:

• Service name and service port
• Service protocol
• Service status (open/close)
• Associated vulnerability count
• Associated Asset

Vulnerabilities¶

Navigate to Vulnerabilities for a consolidated view of all findings across your workspace. Main attributes for each vulnerability include:

• Name
• Severity
• Description
• CVE list
• CVSS score and vector
• Risk score
• Vulnerability status trace
• Associated Asset
• Custom Attributes

For any of these views Vulnerabilities, Assets or Services you can:

• Filter by any field (i.e. severity, status, tool, host, importance, custom attributes, etc)
• Sort by any column
• Customize columns using the column editor (top-right)
• Bulk update status (open, closed, re-opened, risk-accepted) or any other field.

Dashboard¶

Navigate to Dashboard for visual summaries:

• Vulnerability count by severity
• Top vulnerable hosts
• Findings over time
• Scan coverage statistics

5. Create Findings Manually¶

You can also create vulnerabilities by hand — useful for manual penetration testing findings:

1. Navigate to Vulnerabilities
2. Click + Add Vulnerability → Manual Creation
3. Fill in the details:
   • Target asset — Select an existing host (or create a new one first, in the Assets view).
   • Vulnerability name — Choose from the built-in Vulnerability KB or enter a custom name
   • Severity — Critical, High, Medium, Low, or Informational
   • Description, resolution, references — Add context for remediation
4. Click Create

Next Steps¶

Now that you have your first workspace populated with findings, explore these features: