availability

Package: Invicti AppSec Enterprise (on-premise, on-demand)

CodeQL SAST Integration

Invicti Appsec supports CodeQL as a SAST (Static Application Security Testing) scanner. This guide explains how to activate and configure the CodeQL integration.

CodeQL is GitHub's code analysis engine that lets you query code as data. It supports multiple languages and is deeply integrated with GitHub's security ecosystem.

Important: CodeQL integration works only with GitHub or GitHub Enterprise. You must have a GitHub repository configured in Invicti Appsec to use CodeQL.

Prerequisites

Before starting the integration, ensure you have the following information:

Field	Description	Required
Token	GitHub Personal Access Token (PAT) with security_events scope	Yes
URL	GitHub API URL (default: https://api.github.com, or your GitHub Enterprise API URL)	Yes

Get a GitHub Personal Access Token

1. Log in to GitHub.
2. Click on your avatar (upper right-hand corner) and select Settings.
3. Scroll down and click on Developer settings in the left sidebar.
4. Click on Personal access tokens > Tokens (classic).
5. Click Generate new token > Generate new token (classic).
6. Enter a note (token name), set an expiration, and select the security_events scope.
7. Click Generate token and copy the token immediately.

Step 1: Navigate to Integrations

From the left sidebar menu, click on Integrations.

Step 2: Select the SAST Tab

On the Integrations page, you will see the Scanners section with multiple tabs. Click on the SAST tab (it is selected by default).

     

Step 3: Find and Activate CodeQL

Scroll through the list of SAST scanners to find CodeQL.

• If CodeQL is not activated, you will see an "Activate" button. Click it to enable the integration.
• If CodeQL is already activated, you will see a toggle switch in the ON position and a "Deactivate" button, along with a gear icon for configuration.

The scan method badges on the CodeQL card show KDT and UI Import, which means scan results can be triggered through the Invicti Appsec CLI tool or imported via the UI.

:::

Step 4: Configure Connection Settings

Click on the gear icon on the CodeQL card to open the configuration panel. Fill in the required fields:

1. Instance: Select or create an instance name from the dropdown. Use "Default" if you have a single GitHub account.
2. Token: Paste the GitHub Personal Access Token you generated.
3. URL: Enter your GitHub API URL. Use https://api.github.com for GitHub.com, or your GitHub Enterprise API URL (e.g., https://github.your-company.com/api/v3).

  

Step 5: Test the Connection

Click the "Test Connection" button at the bottom of the configuration panel to verify that the provided credentials and URL are correct.

• If the connection is successful, the integration is ready to use.
• If the connection fails, verify your GitHub token has the correct scopes and the URL is correct.
• For existing integrations, you can use the "Retest Connection" button at the top of the panel.

Step 6: Advanced Settings (Optional)

Click on "Advanced Settings" to expand additional options:

Setting	Description	Default
Allow team leads to scan this instance	Permits team leads to trigger scans using this CodeQL instance	Off
Allow team leads to create new instances	Permits team leads to create additional CodeQL instances	Off

After modifying advanced settings, click "Save Advanced Settings" to apply changes.

Summary

Step	Action
1	Navigate to Integrations from the sidebar
2	Select the SAST tab under Scanners
3	Find CodeQL and click Activate (if not already active)
4	Click the gear icon and fill in Token and URL
5	Click Test Connection to verify
6	(Optional) Configure Advanced Settings for team lead permissions

---

Create a Scan

After activating CodeQL, you can create scans from your project's scanner settings.

Navigate to Project Scanners

1. Go to your Project page.
2. Click on the Settings tab.
3. Select Scanners from the left sidebar.

Add CodeQL Scanner

1. In the scanner type dropdown, select SAST.
2. In the scanner dropdown, search for and select CodeQL.
3. Click the Add button to open the scan configuration drawer.

  

Scan Configuration Fields

Field	Description	Required
Environment	Select the environment for the scan (optional)	No
Branch	Specify the branch to scan	No
Meta Data	Additional metadata for the scan (optional)	No
Scan Tag	Tag to identify the scan (optional)	No
Fork Default Branch	Enable to fork the default branch before scanning	No

Scheduler

• Now: Run the scan immediately after saving.
• Custom Date: Schedule the scan for a specific date and time.

Webhook (Optional)

Enable webhook to trigger scans via actions taken on your application lifecycle management tool:

1. Check the Trigger scans via actions checkbox.
2. Select the Platform (e.g., GitHub, GitLab, Bitbucket).
3. Click Generate to create a Secret Key for webhook authentication.

KDT Command

You can also trigger CodeQL scans from your CI/CD pipeline using KDT:

kdt scan -p <project_name> -t codeql -b <branch_name>

Click Save to create the scan configuration.

---

Troubleshooting

Connection Fails

• Invalid Token: Ensure the GitHub Personal Access Token (PAT) has the required scopes (security_events, repo).
• Expired Token: GitHub PATs may have an expiration date. Regenerate the token if it has expired.
• Incorrect URL: Verify the GitHub API URL (e.g., https://api.github.com for GitHub.com or your GitHub Enterprise Server URL).
• Repository Access: Ensure the token owner has access to the repositories with CodeQL results.

Scan Issues

• No SARIF Results: Ensure CodeQL analysis has been run on the repository and SARIF files are available in GitHub Code Scanning.
• Missing Alerts: Verify that CodeQL workflows are configured and have completed successfully in GitHub Actions.

Best Practices

• Use Fine-Grained PATs: When possible, use GitHub fine-grained personal access tokens with minimal repository access.
• Rotate Tokens Regularly: Set token expiration dates and rotate tokens before they expire.
• Use Dedicated Service Accounts: Create a dedicated GitHub user or GitHub App for the Invicti Appsec integration.
• Enable CodeQL in CI/CD: Run CodeQL analysis in your CI/CD pipeline to ensure results are always up to date.

Limitations

• GitHub Dependency: CodeQL results must be available in GitHub Code Scanning. The integration pulls results from GitHub, not directly from CodeQL CLI.
• SARIF Format: Only SARIF-formatted results are supported for import.
• Rate Limits: GitHub API rate limits apply. For large organizations with many repositories, consider using a GitHub App for higher rate limits.

---

Need help?

Invicti Support team is ready to provide you with technical help. Go to Help Center