mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
feature: secret scanning architecture and github data source (wip)
This commit is contained in:
Scott Wilson
@@ -1,175 +0,0 @@
|
||||
---
|
||||
title: 'Secret Scanning'
|
||||
description: "Scan and prevent secret leaks in your code repositories"
|
||||
---
|
||||
|
||||
The Infisical Secret Scanner allows you to keep an overview and stay alert of exposed secrets across your entire GitHub organization and repositories.
|
||||
|
||||
To further enhance security, we recommend you also use our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to scan for exposed secrets prior to pushing your changes.
|
||||
|
||||
|
||||
<Accordion title="Self-hosting">
|
||||
|
||||
To setup secret scanning on your own instance of Infisical, you can follow the steps below.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a GitHub App">
|
||||
Create a new GitHub app in your GitHub organization or personal [Developer Settings](https://github.com/settings/apps).
|
||||
|
||||
|
||||
|
||||
### Configure the GitHub App
|
||||
To configure the GitHub app to work with Infisical, you'll need to modify the following settings:
|
||||
- **Homepage URL**: Required to be set. Set it to the URL of your Infisical instance. (e.g. `https://app.infisical.com`)
|
||||
- **Setup URL**: Set this to `https://<your-infisical-instance.com>/organization/secret-scanning`
|
||||
- **Webhook URL**: Set this to `https://<your-infisical-instance.com>/api/v1/secret-scanning/webhook`
|
||||
- **Webhook Secret**: Set this to a random string. This is used to verify the webhook request from Infisical. Use `openssl rand -base64 32` in your terminal to generate a random secret.
|
||||
|
||||
<Note>
|
||||
Remember to save the webhook secret as you will need it in the next step.
|
||||
</Note>
|
||||
|
||||
|
||||
|
||||
### Configure the GitHub App Permissions
|
||||
The GitHub app needs the following permissions:
|
||||
|
||||
Repository permissions:
|
||||
- `Checks`: Read and Write
|
||||
- `Contents`: Read-only
|
||||
- `Issues`: Read and Write
|
||||
- `Pull Requests`: Read and Write
|
||||
- `Metadata`: Read-only (enabled by default)
|
||||
|
||||
|
||||
|
||||
Subscribed events:
|
||||
- `Check run`
|
||||
- `Pull request`
|
||||
- `Push`
|
||||
|
||||
|
||||
|
||||
|
||||
### Create the GitHub App
|
||||
Now you can create the GitHub app by clicking on the "Create GitHub App" button.
|
||||
|
||||
<Note>
|
||||
If you want other Github users to be able to install the app, you need to tick the "Any account" option under "Where can this GitHub App be installed?"
|
||||
</Note>
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Retrieve the GitHub App ID">
|
||||
After clicking the "Create GitHub App" button, you will be redirected to the GitHub settings page. Here you can copy the "App ID" and save it for later when you need to configure your environment variables for your Infisical instance.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Retrieve your GitHub App slug">
|
||||
The GitHub App slug is the name of the app you created in a slug friendly format. You can find the slug in the URL of the app you created.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Create a new GitHub App private key">
|
||||
Create a new app private key by clicking on the "Generate a private key" button under the "Private keys" section.
|
||||
|
||||
Once you click the "Generate a private key" button, the private key will be downloaded to your computer. Save this file for later as you will need the private key when configuring Infisical.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Remember to save the private key as you will need it in the next step.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
|
||||
<Step title="Configure your Infisical instance">
|
||||
Now you can configure your Infisical instance by setting the following environment variables:
|
||||
|
||||
- `SECRET_SCANNING_GIT_APP_ID`: The App ID of your GitHub App.
|
||||
- `SECRET_SCANNING_GIT_APP_SLUG`: The slug of your GitHub App.
|
||||
- `SECRET_SCANNING_PRIVATE_KEY`: The private key of your GitHub App that you created in a previous step.
|
||||
- `SECRET_SCANNING_WEBHOOK_SECRET`: The webhook secret of your GitHub App that you created in a previous step.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
After restarting your Infisical instance, you should be able to use the secret scanning feature within your organization. Follow the steps below to add the GitHub App to your Infisical organization.
|
||||
</Accordion>
|
||||
|
||||
## Install the Infisical Radar GitHub App
|
||||
|
||||
To install the GitHub App, press the "Integrate With GitHub" button in the top right corner of your Infisical Secret Scanning dashboard.
|
||||
|
||||
|
||||
|
||||
Next, you'll be prompted to select which organization you'd like to install the app into. Select the organization you'd like to install the app into by clicking the organization in the menu.
|
||||
|
||||
|
||||
|
||||
Select the repositories you'd like to scan for secrets and press the "Install" button.
|
||||
|
||||
|
||||
|
||||
## Code Scanning
|
||||
|
||||
|
||||
|
||||
Secret scans are built on event-driven architecture. This means that every time a push is made to one of your selected repositories, Infisical will scan the modified files for any exposed secrets.
|
||||
|
||||
If one or more exposed secrets are detected, it will be displayed in your Infisical dashboard. An exposed secret is known as a **"Risk"**. Each risk has the following data associated with it:
|
||||
- **Date**: When the risk was first detected.
|
||||
- **Secret Type**: Which type of secret was detected.
|
||||
- **Info**: Information about the secret, such as the repository, file name, and the committer who made the change.
|
||||
|
||||
Once an exposed secret is detected, all organization admins will be sent an e-mail notification containing details about the exposed secret.
|
||||
|
||||
<Tip>
|
||||
Each risk also contains a "View Exposed Secret" button, which will take you directly to the GitHub commit and to the line where the secret was exposed.
|
||||
</Tip>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Responding to Exposed Secrets
|
||||
|
||||
After an exposed secret is detected, it will be marked as `Needs Attention`. When there are risks marked as needs attention, it's important to address them as soon as possible.
|
||||
|
||||
You can mark the risk as `Resolved` by changing the status to one of the following states:
|
||||
- **This Is a False Positive**: The secret was not exposed, but was detected by the scanner.
|
||||
- **I Have Rotated The Secret**: The secret was exposed, but it has now been removed.
|
||||
- **No Rotation Needed**: You are choosing to ignore this risk. You may choose to do this if the risk is non-sensitive or otherwise not a security risk.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Ignoring Known Secrets
|
||||
If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
|
||||
|
||||
### infisical-scan:ignore
|
||||
|
||||
To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
|
||||
|
||||
```js example.js
|
||||
function helloWorld() {
|
||||
console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
|
||||
}
|
||||
```
|
||||
|
||||
### .infisicalignore
|
||||
An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
|
||||
You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
|
||||
By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
|
||||
|
||||
```.ignore .infisicalignore
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
|
||||
1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
|
||||
```
|
||||
117
docs/documentation/platform/secret-scanning/overview.mdx
Normal file
117
docs/documentation/platform/secret-scanning/overview.mdx
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: "Secret Scanning"
|
||||
sidebarTitle: "Overview"
|
||||
description: "Scan and prevent secret leaks in your code repositories"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Monitor and detect exposed secrets across your data sources, including code repositories, with Infisical Secret Scanning.
|
||||
|
||||
For additional security, we recommend using our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to check for exposed secrets before pushing your code changes.
|
||||
|
||||
## How Secret Scanning Works
|
||||
|
||||
Secret Scanning consists of several components that enable you to quickly respond to secret leaks:
|
||||
|
||||
- **Scanner Engine**: The core component that analyzes your code and detects potential secrets using pattern matching and entropy analysis
|
||||
- **Real-time Monitoring**: Provides continuous surveillance of your repositories for immediate detection of exposed secrets
|
||||
- **Alert System**: Notifies organization admins via email when secrets are detected
|
||||
- **Risk Management**: Allows tracking and managing detected secrets with different status options
|
||||
- **Data Sources**: Integrates with various data sources and version control systems
|
||||
- **Customizable Rules**: Supports ignore patterns and custom configurations to reduce false positives
|
||||
|
||||
These components work together to provide comprehensive secret detection and incident response capabilities.
|
||||
|
||||
### Data Sources
|
||||
|
||||
Data sources are configured integrations with external platforms, such as a GitHub organization or a GitLab group, that establish secure connections for scanning purposes using [App Connections](/integrations/app-connections/overview).
|
||||
|
||||
A data source acts as a secure intermediary between the external system and the scanner engine. It manages a collection of scannable resources (such as repositories) and handles the authentication and communication required for scanning operations.
|
||||
|
||||
[data source page image]
|
||||
|
||||
### Resources
|
||||
|
||||
Resources are the atomic, scannable units, such as a repository, that can be monitored for secret exposure. Resources are added automatically when a data source is scanned and updated when scanning events are triggered, such as when a user pushes changes to GitHub.
|
||||
|
||||
Each resource maintains its own scanning history and status, allowing for granular monitoring and management of secret scanning across your organization.
|
||||
|
||||
[resource table image]
|
||||
|
||||
### Scans
|
||||
|
||||
Scans can be initiated in two ways:
|
||||
|
||||
1. **Full Scan** - Manually triggered scan that comprehensively checks either:
|
||||
- All resources associated with a data source
|
||||
- A single selected resource
|
||||
|
||||
2. **Diff Scan** - Automatically executed when **Auto-Scan** is enabled on a data source. This scan type specifically focuses on updates to existing resources.
|
||||
|
||||
All scan activities can be monitored in real-time through the Infisical UI, which displays:
|
||||
- Current scan status
|
||||
- Timestamp of the scan
|
||||
- Resource(s) being scanned
|
||||
- Detection results (whether any secrets were found)
|
||||
|
||||
[scan table image]
|
||||
|
||||
## [In Progress - old below]
|
||||
|
||||
## Code Scanning
|
||||
|
||||
|
||||
|
||||
Secret scans are built on event-driven architecture. This means that every time a push is made to one of your selected repositories, Infisical will scan the modified files for any exposed secrets.
|
||||
|
||||
If one or more exposed secrets are detected, it will be displayed in your Infisical dashboard. An exposed secret is known as a **"Risk"**. Each risk has the following data associated with it:
|
||||
- **Date**: When the risk was first detected.
|
||||
- **Secret Type**: Which type of secret was detected.
|
||||
- **Info**: Information about the secret, such as the repository, file name, and the committer who made the change.
|
||||
|
||||
Once an exposed secret is detected, all organization admins will be sent an e-mail notification containing details about the exposed secret.
|
||||
|
||||
<Tip>
|
||||
Each risk also contains a "View Exposed Secret" button, which will take you directly to the GitHub commit and to the line where the secret was exposed.
|
||||
</Tip>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Responding to Exposed Secrets
|
||||
|
||||
After an exposed secret is detected, it will be marked as `Needs Attention`. When there are risks marked as needs attention, it's important to address them as soon as possible.
|
||||
|
||||
You can mark the risk as `Resolved` by changing the status to one of the following states:
|
||||
- **This Is a False Positive**: The secret was not exposed, but was detected by the scanner.
|
||||
- **I Have Rotated The Secret**: The secret was exposed, but it has now been removed.
|
||||
- **No Rotation Needed**: You are choosing to ignore this risk. You may choose to do this if the risk is non-sensitive or otherwise not a security risk.
|
||||
|
||||
|
||||
|
||||
## Ignoring Known Secrets
|
||||
If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
|
||||
|
||||
### infisical-scan:ignore
|
||||
|
||||
To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
|
||||
|
||||
```js example.js
|
||||
function helloWorld() {
|
||||
console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
|
||||
}
|
||||
```
|
||||
|
||||
### .infisicalignore
|
||||
An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
|
||||
You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
|
||||
By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
|
||||
|
||||
```.ignore .infisicalignore
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
|
||||
1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
|
||||
```
|
||||
Reference in New Issue
Block a user