Skip to main content

Guides for Security Engineers

These guides cover advanced configuration: authenticated scanning, deploying scan agents inside private networks, creating reusable templates, and setting up continuous scanning.

Guide 1: Setting Up Authenticated Scanning​

Authenticated scans find significantly more vulnerabilities than unauthenticated ones because they can test pages and APIs behind login screens.

Time needed15 minutes
PrerequisitesThreatWeaver account with Engineer or Admin role; test credentials for the target application
What you'll learnHow to create an auth profile, test it, and attach it to a scan

Why authenticated scanning matters​

Without authentication, the scanner can only test publicly accessible pages. With a login, it can reach admin panels, user dashboards, API endpoints that require tokens, and more. This is where most critical vulnerabilities hide.

Steps​

  1. Navigate to AppSec > Credentials. From the AppSec sidebar, click Credentials. This is where you manage authentication profiles.

  2. Click "+ New Auth Profile". Choose the authentication type that matches your target application:

    Auth TypeWhen to use it
    Form LoginStandard username/password login page (most web apps).
    API TokenBearer token or API key-based authentication (REST APIs).
    OAuth 2.0OAuth2 client credentials or authorization code flow.
    Cookie-BasedYou manually provide session cookies.
    Custom HeaderCustom authentication header (e.g., X-API-Key).

  3. Fill in the credentials.

    For Form Login (the most common type):

    • Login URL: The URL of the login page (e.g., https://staging.myapp.com/login)
    • Username field: The HTML name or ID of the username input (e.g., email)
    • Password field: The HTML name or ID of the password input (e.g., password)
    • Username: Your test account username
    • Password: Your test account password
    • Success indicator: A string that appears after successful login (e.g., "Dashboard" or "Welcome")
    Use dedicated test accounts

    Never use real user credentials. Create a dedicated test account with the minimum permissions needed. This protects real users and ensures the scan doesn't accidentally modify production data.

  4. Test the auth profile. Click Test Login. ThreatWeaver will attempt to log in using your credentials and report whether it succeeded. If the test passes, you will see a green checkmark and the authenticated session details.

    If the test fails, check:

    • Is the login URL correct and accessible from ThreatWeaver?
    • Are the field names correct? (Inspect the login form HTML to verify.)
    • Does the application use CAPTCHA or rate limiting that blocks automated login?
    • Does the application require MFA? If so, consider using API Token auth instead.

  5. Attach the auth profile to an assessment. When creating or editing an assessment, select your auth profile in the Authentication section. The scanner will log in before starting its tests.

  6. Set up multi-user context (optional). For thorough authorization testing (BOLA, BFLA, IDOR), configure two users with different permission levels:

    • User A: Regular user (e.g., analyst@test.com)
    • User B: Admin user (e.g., admin@test.com)

    The scanner will test whether User A can access User B's resources, detecting broken access control.

Auth profile security

Credentials are encrypted at rest and never logged in scan results. Only users with Engineer or Admin roles can view or edit auth profiles.

Guide 2: Deploying a Docker Scan Agent for Internal Networks​

When your application runs behind a firewall and is not accessible from the internet, you can deploy a scan agent inside your network.

Time needed20 minutes
PrerequisitesDocker installed on a machine inside your internal network; ThreatWeaver Admin role
What you'll learnHow to deploy an agent, connect it to ThreatWeaver, and assign scan targets

Architecture overview​

The scan agent connects outbound to ThreatWeaver via WebSocket over HTTPS. No inbound firewall rules are needed. All scan traffic stays inside your network -- only results and coordination messages travel over the WebSocket connection.

Steps​

  1. Navigate to AppSec > Sensors. From the AppSec sidebar, click Sensors (sometimes labeled "Agents" depending on your version).

  2. Generate an enrollment token. Click + Enroll New Sensor. ThreatWeaver generates a one-time enrollment token and displays the Docker run command.

  3. Copy the Docker run command. It looks something like this:

    docker run -d \
      --name tw-agent \
      --restart unless-stopped \
      -e ENROLLMENT_TOKEN=eyJhbGciOiJFUzI1NiIs... \
      -e PLATFORM_URL=https://api.threatweaver.ai \
      threatweaver/scan-agent:latest

  4. Run the command on your internal machine. SSH into the machine inside your network and run the command. The agent will:

    • Pull the Docker image
    • Connect to ThreatWeaver using the enrollment token
    • Register itself in the agent fleet

  5. Wait for the agent to appear. Back in ThreatWeaver, refresh the Sensors page. Your new agent should appear within 30 seconds with a Connected status.

  6. Assign a scan target to the agent. When creating an assessment for an internal application, select your agent in the Sensor dropdown. The scan will run through that agent instead of the default cloud scanner.

Network requirements​

DirectionProtocolPortPurpose
OutboundHTTPS443WebSocket connection to ThreatWeaver
InternalHTTP/HTTPSAnyAgent connects to your internal applications
No inbound rules needed

The agent only makes outbound connections. You do not need to open any inbound ports on your firewall.

Troubleshooting​

SymptomCauseFix
Agent shows "Disconnected"Network or proxy blocking outbound WebSocketCheck that wss://api.threatweaver.ai is allowed through your proxy
Agent can't reach targetDNS or routing issue inside your networkVerify the agent machine can curl the target URL
Enrollment token expiredTokens expire after 24 hoursGenerate a new token from the Sensors page

Guide 3: Configuring Scan Templates​

Scan templates let you save and reuse scan configurations so you don't have to reconfigure settings for every assessment.

Time needed10 minutes
PrerequisitesEngineer or Admin role
What you'll learnHow to create and share custom scan templates

What templates control​

SettingDescription
Scan ScopeWhich types of tests to run (e.g., injection only, full DAST, API-focused).
Scan DepthHow aggressively the scanner explores (number of endpoints, parameter fuzzing depth).
Agent SelectionWhich of the 59 agents are enabled. You can disable agents for specific use cases.
TimeoutMaximum scan duration before auto-stop.
Auth ProfileDefault authentication configuration.
Compliance MappingWhich frameworks to map findings against (PCI-DSS, SOC 2, etc.).

Steps​

  1. Navigate to AppSec > Templates. Click Templates in the AppSec sidebar.

  2. Click "+ New Template". Give your template a descriptive name (e.g., "API Full Scan" or "PCI Compliance Check").

  3. Configure the settings.

    For an API-focused scan:

    • Enable API-specific agents: apiSecurityAgent, owaspApiTop10Agent, graphqlAgent, specConformanceAgent, massAssignmentAgent
    • Disable browser-focused agents: domXssAgent, csrfTester
    • Set scope to "API endpoints only"

    For a compliance-focused scan:

    • Enable all agents (maximum coverage)
    • Turn on compliance mapping for your required frameworks
    • Set timeout to allow a thorough scan (60-90 minutes)

  4. Save the template. Click Save. The template is now available when creating new assessments.

  5. Share with your team. Templates are visible to all users in your tenant. Use clear naming conventions so everyone knows which template to pick.

Template naming convention

Use a prefix that describes the use case: API-* for API scans, COMPLIANCE-* for audit prep, QUICK-* for fast checks, FULL-* for comprehensive scans.

Guide 4: Setting Up Continuous Scanning Schedules​

One-time scans catch vulnerabilities at a point in time. Continuous scanning catches new vulnerabilities as your application changes.

Time needed10 minutes
PrerequisitesAt least one target and template configured
What you'll learnHow to schedule recurring scans and integrate with CI/CD

Scheduling options​

Schedule TypeBest For
DailyHigh-change applications with frequent deployments.
WeeklyMost applications -- good balance of coverage and cost.
On-CommitCI/CD integration -- scan every time code is pushed.
MonthlyStable applications that change infrequently.

Steps: Scheduled scans​

  1. Navigate to AppSec > Assessments.
  2. Click "+ New Assessment" or edit an existing one.
  3. In the Schedule section, select your frequency (Daily, Weekly, Monthly).
  4. Set the day and time (e.g., every Monday at 2:00 AM).
  5. Choose whether to notify on completion -- enable webhook or email notifications so you know when results are ready.
  6. Save the assessment.

The scan will run automatically on schedule. Results appear in the assessment history.

Steps: CI/CD integration via GitHub Action​

For on-commit scanning, add a GitHub Action to your repository:

# .github/workflows/threatweaver-scan.yml
name: ThreatWeaver Security Scan

on:
  pull_request:
    branches: [main, dev]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger ThreatWeaver Scan
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.TW_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"targetId": "your-target-id", "templateId": "your-template-id"}' \
            https://api.threatweaver.ai/api/appsec/assessments/trigger

      - name: Wait for Results
        run: |
          # Poll for scan completion (simplified example)
          echo "Scan triggered. Check ThreatWeaver for results."
Webhook notifications

You can configure webhooks to post scan results directly to your PR as a comment. See the Webhooks guide for setup instructions.

Next steps​