Guides for Administrators

These guides cover platform administration: managing users, configuring SSO, setting data retention policies, connecting to Tenable, and monitoring system health.

---

Guide 1: Managing Users and Roles

Control who has access to ThreatWeaver and what they can do.

Time needed	10 minutes
Prerequisites	Admin role
What you'll learn	How to add users, assign roles, deactivate accounts, and manage access

User roles explained

Role	What they can do
Admin	Full platform access. Manage users, configure settings, view all data.
Manager	View dashboards, manage team assignments, approve exceptions, run reports.
Security Analyst	Run scans, review findings, create exceptions, generate reports.
Scanner Admin	Manage scan agents, templates, credentials, and scan schedules.
Compliance Officer	View compliance reports, manage exceptions, access audit logs.
Analyst	View findings and dashboards. Cannot modify configurations.
Viewer	Read-only access to dashboards and reports.

Steps: Adding a new user

1. Navigate to Admin > User Management.
2. Click "+ Add User".
3. Fill in the user details:
   • Display name
   • Email address (this is their login)
   • Role (select from the table above)
4. Click Save. The user will receive an email invitation with a link to set their password.

Seat limits

Your license defines how many users (seats) you can have. The user management page shows current usage (e.g., "12 of 25 seats used"). If you need more seats, contact your account manager or check Settings > License.

Steps: Changing a user's role

1. Navigate to Admin > User Management.
2. Find the user using the search bar.
3. Click the user's row to open their profile.
4. Change the Role dropdown to the new role.
5. Save. The change takes effect immediately on their next page load.

Steps: Deactivating a user

When someone leaves the team:

1. Navigate to Admin > User Management.
2. Find the user and click their row.
3. Click "Deactivate Account". The user can no longer log in, but their historical activity (scan results, exception approvals, audit logs) is preserved.

Don't delete -- deactivate

Deleting a user permanently removes their audit trail. Always deactivate instead to maintain compliance records.

Bulk user management

For large teams, you can import users via CSV:

1. Click "Import Users" on the User Management page.
2. Download the CSV template.
3. Fill in name, email, and role for each user.
4. Upload the CSV. ThreatWeaver will create accounts and send invitations.

---

Guide 2: Configuring SSO with Microsoft Entra ID

Enable single sign-on so your team can log in with their corporate Microsoft accounts.

Time needed	30 minutes
Prerequisites	Admin role in ThreatWeaver; Global Admin or Application Admin in Microsoft Entra ID (Azure AD)
What you'll learn	How to configure SAML SSO between ThreatWeaver and Microsoft Entra ID

Overview

Steps

1. Register ThreatWeaver in Microsoft Entra ID.

   • Log in to the Azure Portal.
   • Go to Microsoft Entra ID > Enterprise Applications > + New Application.
   • Click Create your own application.
   • Name it "ThreatWeaver" and select "Integrate any other application you don't find in the gallery (Non-gallery)".
   • Click Create.

2. Configure SAML settings.

   • In the new application, go to Single sign-on > SAML.
   • Set the Basic SAML Configuration:

   Field	Value
   Identifier (Entity ID)	https://api.threatweaver.ai/api/sso/metadata
   Reply URL (ACS URL)	https://api.threatweaver.ai/api/sso/callback
   Sign on URL	https://app.threatweaver.ai/login

3. Set redirect URIs. Under the app registration, go to Authentication > Platform configurations > Web and add:

   • https://api.threatweaver.ai/api/sso/callback

4. Map user attributes. Under Attributes & Claims, configure:

   Claim	Source Attribute
   email	user.mail
   name	user.displayname
   role	user.assignedroles (optional -- for automatic role mapping)

5. Download the Federation Metadata XML. Under SAML Signing Certificate, click Download next to "Federation Metadata XML".

6. Configure ThreatWeaver.

   • In ThreatWeaver, go to Admin > SSO Config.
   • Upload the Federation Metadata XML, or manually enter:
     • SSO Login URL (from Entra)
     • SSO Certificate (from Entra)
     • Entity ID (from Entra)
   • Click Save and then Test SSO Login.

7. Test the SSO login. Open a private/incognito browser window and navigate to ThreatWeaver. Click "Sign in with SSO". You should be redirected to Microsoft, prompted to log in, and then returned to ThreatWeaver.

8. Enforce SSO (optional). Once SSO is confirmed working, you can disable password-based login:

   • In Admin > SSO Config, toggle Enforce SSO for all users.
   • Users will no longer be able to log in with email/password.
   Keep at least one local admin

   Before enforcing SSO, ensure you have a local admin account as a break-glass option. If your identity provider has an outage, you need a way to log in.

Troubleshooting

Symptom	Cause	Fix
"SSO redirect loop"	Reply URL mismatch	Verify the ACS URL in Entra matches exactly what ThreatWeaver expects.
"User attributes not mapping"	Claim names don't match	Check that the claim names in Entra match what ThreatWeaver expects (email, name).
"User created but wrong role"	Role claim not configured	Set up role mapping in Entra or manually assign roles after first login.

---

Guide 3: Setting Up Data Retention Policies

Control how long ThreatWeaver keeps different types of data to meet compliance requirements and manage storage.

Time needed	10 minutes
Prerequisites	Admin role
What you'll learn	How to configure retention periods, archive data, and understand the impact on compliance

Why data retention matters

• Compliance: Regulations like PCI-DSS and HIPAA have specific data retention requirements.
• Storage: Old scan data accumulates over time and can impact performance.
• Privacy: Retaining data longer than necessary increases risk exposure.

Steps

1. Navigate to Admin > Data Retention.

2. Configure retention periods per data type:

   Data Type	Default Retention	Common Settings
   Scan findings	1 year	PCI-DSS requires 1 year minimum.
   Scan results (raw data)	90 days	Detailed request/response evidence.
   Audit logs	2 years	SOC 2 typically requires 1+ years.
   Vulnerability history	Indefinite	Needed for trend analysis.
   User activity logs	1 year	Login history, action audit trail.

3. Set the archival policy. When data passes its retention period, it can be:

   • Archived -- moved to compressed storage, still retrievable
   • Deleted -- permanently removed (irreversible)
   Archive before deleting

   Always archive first. Archived data can be restored if needed for an audit. Deleted data is gone forever.

4. Save and review. Changes take effect on the next nightly cleanup cycle. You can also trigger an immediate cleanup from this page.

Impact on compliance reports

• Compliance reports can only include data that still exists. If you set findings retention to 90 days, you cannot generate a compliance report for the past year.
• Archived data is included in compliance reports if it is restored first.

---

Guide 4: Configuring API Keys for Tenable Integration

Connect ThreatWeaver to your Tenable.io account to sync vulnerability and asset data.

Time needed	15 minutes
Prerequisites	Admin role in ThreatWeaver; Admin access to Tenable.io
What you'll learn	How to generate Tenable API keys, enter them in ThreatWeaver, and run your first sync

Steps

1. Generate API keys in Tenable.io.

   • Log in to Tenable.io.
   • Click your profile icon (top right) > My Account > API Keys.
   • Click Generate. You will see an Access Key and a Secret Key.
   • Copy both immediately -- the secret key is only shown once.
   Protect these keys

   Tenable API keys have full access to your Tenable.io account. Treat them like passwords. Never share them in email, chat, or version control.

2. Enter keys in ThreatWeaver.

   • In ThreatWeaver, go to Admin > API Config.
   • Enter the Access Key and Secret Key in the Tenable configuration section.
   • The Cloud URL should be https://cloud.tenable.com (the default).
   • Click Save.

3. Test the connection. Click Test Connection. ThreatWeaver will make a test API call to Tenable.io and verify that the keys work. You should see a green "Connection successful" message.

4. Run the first sync.

   • Go to Admin > API Sync.
   • Click Sync Now.
   • The first sync may take 5-30 minutes depending on how much data is in your Tenable account.
   • You will see progress indicators showing chunks being imported.

5. Verify the sync. After the sync completes:

   • Go to the Exposure Management dashboard. You should see asset counts and vulnerability metrics.
   • Check Admin > API Sync for sync history and any errors.

What to expect after the first sync

Data	What appears
Assets	All hosts from Tenable.io, categorized by OS type.
Vulnerabilities	All open vulnerabilities with CVSS scores and plugin details.
Dashboard	KPI cards populate with real data (total vulns, critical count, WeaverScore).

Troubleshooting

Symptom	Cause	Fix
"Sync stuck at 0%"	API keys invalid or expired	Regenerate keys in Tenable.io and re-enter them.
"No assets appearing"	Tenable account has no scan data	Run a scan in Tenable.io first, then sync.
"Sync completes but numbers seem low"	Export permissions limited	Ensure the API key user has admin-level export permissions in Tenable.io.
"Connection test fails"	Network/proxy blocking outbound	Verify that ThreatWeaver can reach cloud.tenable.com on port 443.

---

Guide 5: Monitoring Platform Health

Keep an eye on scanner agents, system performance, and database health.

Time needed	5 minutes (daily check)
Prerequisites	Admin role
What you'll learn	How to check scanner health, database size, and troubleshoot performance

Daily health check

1. Navigate to Admin > System Settings. This page shows an overview of platform status.

2. Check scanner health. Go to Admin > WeaverScan to see all registered scan agents:

   Status	Meaning
   Connected	Agent is online and ready to scan.
   Disconnected	Agent lost connection. Check the host machine.
   Scanning	Agent is currently running a scan.
   Idle	Agent is connected but not actively scanning.

3. Review recent sync status. Go to Admin > API Sync to verify the most recent Tenable sync completed successfully. Look for:

   • Last sync time (should be within your configured schedule)
   • Any error messages in the sync history

4. Check database utilization. In Admin > System Settings, look at storage metrics:

   • Total database size
   • Findings count
   • Growth rate
   When to archive

   If your database is growing faster than expected, review your data retention policies and archive old scan data.

5. Review security audit logs. Go to Admin > Security Audit to check for:

   • Failed login attempts (potential brute force)
   • Unusual API activity
   • Configuration changes by other admins

Performance troubleshooting

Symptom	Possible Cause	Action
Dashboard loads slowly	Large dataset without caching	Check if Redis cache is configured (production). Review data retention to reduce dataset size.
Scans timing out	Target is slow or agent overloaded	Increase scan timeout in the template. Check agent resource utilization.
Sync takes too long	Large Tenable export	This is normal for initial syncs. Subsequent incremental syncs will be faster.

---

Next steps

• Managing Users and Roles -- complete your team setup
• Deploying Docker Scan Agents -- extend scanning into your internal network
• Setting Up Webhooks -- get notified about platform events
• Glossary -- look up unfamiliar terms