Configure GitHub Issues Integration

Connect AttackLens to a GitHub repository to create issues directly from security findings. This integration is well-suited for teams that track security remediation work alongside their code in GitHub.

INFO

Requires Admin role or higher.

Prerequisites

Before configuring the GitHub Issues integration, ensure you have:

• GitHub repository: The full name of the repository where issues will be created (e.g., your-org/security-findings).
• Personal access token: A GitHub personal access token with the repo scope (classic) or Issues read/write permission (fine-grained). See Creating a GitHub Token below.
• Network access: Your AttackLens backend must be able to reach api.github.com (GitHub.com) or your GitHub Enterprise Server API endpoint over HTTPS.

Step 1: Navigate to Issue Integrations

Go to Integrations > Issue Integrations in the left sidebar and click Create Integration.

Step 2: Select GitHub Issues

Select GitHub Issues from the integration type list.

Step 3: Configure Connection

Fill in the connection details:

API URL

• GitHub.com: Leave as the default https://api.github.com.
• GitHub Enterprise Server: Enter your Enterprise API URL (e.g., https://github.yourcompany.com/api/v3).

Personal Access Token (Required)

The GitHub personal access token used to authenticate API requests.

Repository (Required)

The full repository name in owner/repo format:

your-org/security-findings

The repository must already exist. AttackLens does not create repositories.

TIP

Consider creating a dedicated repository for security findings (e.g., security-findings or vulnerability-tracking) rather than mixing them into a code repository. This keeps security issues organized and allows you to manage access separately.

Step 4: Configure Label Mapping

Labels help organize and filter issues in GitHub. Configure how AttackLens data maps to GitHub labels.

Severity Labels

Map finding severities to GitHub labels. AttackLens will automatically add these labels when creating issues:

AttackLens Severity	GitHub Label (Default)
Critical	severity:critical
High	severity:high
Medium	severity:medium
Low	severity:low
Informational	severity:info

INFO

AttackLens will create these labels in the repository automatically if they do not already exist. You can customize the label names and colors.

Additional Labels (Optional)

Add static labels that are applied to every issue created by AttackLens. Common examples:

• attacklens -- To identify issues created by the integration.
• security -- For general categorization.
• compliance -- For posture-related findings.

Assignees (Optional)

Specify default assignees for created issues. Enter GitHub usernames. The assigned users must have access to the repository.

Step 5: Configure Field Mapping

Map AttackLens finding fields to GitHub issue fields:

AttackLens Field	GitHub Field	Notes
Finding title	Issue title	Always mapped.
Finding description + remediation	Issue body	Formatted as GitHub-flavored Markdown with sections for description, affected asset, severity, and remediation steps.
Severity	Labels	Based on the severity label mapping above.
Policy/Ruleset name	Labels (optional)	Optionally added as a label for categorization.
Affected asset name	Body section	Included in the issue body under an "Affected Asset" heading.

Step 6: Test the Connection

Click Test Connection to verify that AttackLens can reach GitHub and authenticate successfully. The test will:

1. Authenticate with the provided token.
2. Verify the repository exists and is accessible.
3. Verify the token has permission to create issues.
4. Validate any configured assignees are valid collaborators.

WARNING

If the test fails, check the following:

• The API URL is correct (https://api.github.com for GitHub.com).
• The personal access token has not expired.
• The token has the repo scope (classic) or Issues read/write permission (fine-grained).
• The repository name is in the correct owner/repo format.
• Your AttackLens backend can reach the GitHub API (check firewall rules for outbound HTTPS).

Step 7: Save

Click Save to create the integration. The token is encrypted at rest in the AttackLens database.

Creating a GitHub Token

Fine-Grained Personal Access Token (Recommended)

1. Go to https://github.com/settings/tokens?type=beta.
2. Click Generate new token.
3. Set a Token name (e.g., "AttackLens Integration").
4. Set the Expiration (90 days recommended; rotate before expiry).
5. Under Repository access, select Only select repositories and choose the target repository.
6. Under Permissions > Repository permissions, set Issues to Read and write.
7. Click Generate token.
8. Copy the token immediately.

Classic Personal Access Token

1. Go to https://github.com/settings/tokens.
2. Click Generate new token (classic).
3. Set a Note (e.g., "AttackLens Integration").
4. Select the repo scope.
5. Click Generate token.
6. Copy the token immediately.

TIP

Fine-grained tokens are preferred because they can be scoped to a specific repository with only the permissions needed. Classic tokens grant access to all repositories the user can access.

Using the Integration

After configuration, you can create GitHub issues from findings:

1. Navigate to Findings.
2. Select one or more findings.
3. Click Create Issue.
4. Select the GitHub Issues integration.
5. Review the mapped fields and click Create.

The created issue URL is logged in the integration's issue history. See Manage Integrations for details.