Understand the monitored perimeter
Overview
Your perimeter is simply anywhere you are storing your shared code repositories. This includes shared repository hosting like GitHub, GitLab, Bitbucket or Azure Repos.
Your perimeter page has two main objectives:
- Identify which of your sources are at risk
- Ensure that your entire perimeter is well protected by GitGuardian
For effective navigation in the perimeter table, users can leverage Saved views to switch between different sets of filters. The feature includes non-editable GitGuardian views such as "All sources," "Critical sources," "Scanning issues", "With open secret incidents", "Without honeytoken".
At the bottom of the right-hand side panel, the scope section gives you a quick summary of the different integrations (VCS types) that have been integrated with GitGuardian, alongside a breakdown of sources per integration.
Differences between historical scanning and real-time protection
Real-time monitoring
The first protection and the most effective one for secrets remediation is the real-time monitoring.
As you may have read in our How GitGuardian works section, real-time monitoring means that every single push event (and its commits) is scanned for secrets as soon as they arrive on your VCS server (post-receive hooks).
We then alert you instantly, which will save you time in the remediation process. Indeed, the longer a secret is exposed, the harder the remediation gets.
On the right-hand side panel, we indicate the percentage of sources covered, based on the number of sources you integrated with GitGuardian. Note that some sources may not be eligible to be monitored because of plan restrictions.
Note that the table of sources displayed on the Perimeter page only contains sources that are monitored in real-time. The sources that are not selected in the integration settings page are not displayed.
For performance reasons, we limit the number of commits scanned per push event. By default, this limit is 1,000 scanned commits/push event, but this can be customized per workspace on demand.
Historical scanning
The second type of protection offered is the ability to scan the commit history of all the sources you integrated with GitGuardian.
Size limitations apply to historical scans, depending on your plan:
- Free: you can scan sources up to 1GB,
- Business and trial: you can scan sources up to 12 GB.
For performance reasons, if a historical scan is requested for a repository that has had no new commits on any branch since the last historical scan, GitGuardian will skip the scan to avoid reprocessing the entire history. However, if the tokenscanner version has changed since the last historical scan—with GitGuardian having introduced new detectors—the scan will proceed, even if there are no new commits.
Potential Errors During Historical Scanning and Their Resolutions
| Reason | Error Message | Steps to Resolve |
|---|---|---|
| DMCA takedown | The source is unavailable due to a DMCA takedown. | Contact the source owner to discuss the DMCA takedown. |
| Access to the repository is disabled | The source has been disabled. | Reach out to the source owner to request re-enabling access to the repository. |
| Account has been disabled | The source’s account has been disabled. | Contact the source owner to resolve the account issues and regain access. |
| Access to repository restricted by IP | The source’s account has a configured IP allow list. | Contact the source owner to review and adjust the IP allow list. |
| Repository not found | The source could not be found. Please retry and contact the source owner if it persists. | Double-check the repository URL and retry. Contact the source owner if the issue persists. |
| Clone operation stuck or too slow | The connection to the server is slow or stuck. | Contact the VCS administrator to investigate server connection issues. |
| VCS not ready or responded with an error | The server did not respond after multiple attempts. | Reach out to the VCS administrator to ensure the server is operational and retry the scan. |
| Repository disabled in GitLab project | The git repository in the GitLab project has been disabled. | Enable the “repository” functionality in the settings of the GitLab project. |
| The repository has been deleted | The target repository has been deleted. | Contact the VCS administrator to confirm and address the deletion of the repository. |
| VCS authentication error | The authentication to the VCS has failed. | Verify authentication token under Settings > Integrations and contact the VCS administrator if needed. |
| Rate limit error | The rate limit has been exceeded. | Wait for the rate limit to reset or contact the VCS administrator for a resolution. |
| Too Large | The historical scan failed because it exceeded the authorized size limit. | Contact GitGuardian support to discuss options for scanning larger repositories. For self-hosted environments, consider adjusting the repo_scan_size_limit in the preferences within the Admin area. |
| Timeout | The historical scan failed due to a timeout error because it exceeded the authorized time limit for an individual scan. | Contact GitGuardian support for troubleshooting and to potentially extend the scan time limit. For self-hosted environments, consider adjusting the repo_scan_time_limit_in_sec in the preferences within the Admin area. |
| Timeout Pending | The historical scan failed due to a timeout error because it exceeded the authorized time limit for a bulk scan. Please contact our support. | Contact GitGuardian support to address bulk scan timeouts and explore alternative solutions. For self-hosted environments, consider adjusting the repo_scan_pending_limit_in_hours in the preferences within the Admin area. |
| Scan worker error | The scan failed due to an internal worker error, often caused by memory limitations. | Please reach out to our support team. If you are running GitGuardian in a self-hosted environment, consider increasing the memory allocation for workers to resolve the issue. Additionally, generate a Support Bundle for further troubleshooting purposes. |
| Engine error | The scan failed due to an internal engine error. | Please reach out to our support team. If you are running GitGuardian on a self-hosted environment, generate a Support Bundle for troubleshooting purposes. |
| Process received SIGKILL | The scan process was forcibly terminated (SIGKILL). | Please reach out to our support team. If you are running GitGuardian on a self-hosted environment, generate a Support Bundle for troubleshooting purposes. |
| Unknown | The scan failed due to an unknown error. | Please reach out to our support team. If you are running GitGuardian on a self-hosted environment, generate a Support Bundle for troubleshooting purposes. |
Historical scanning is also available for Slack. You can scan the entire history of your monitored public and private Slack channels. Conversations and archived channels are not supported.
Note that historical scanning is subject to the Slack's API rate limiting. We can scan up to 10.000 messages/min per Slack workspace.
Historical Scan reports of Slack and VCS are sent separately.
Source status
Monitored source
A source is considered as monitored when the GitGuardian platform is listening for any activity on that source.
This is the outcome of:
- successfully integrating GitGuardian with the source
- and having a plan that supports its monitoring.
Monitored sources are listed on the Perimeter page.
No longer monitored source
A source is considered as no longer monitored when the GitGuardian is no longer listening to any activity on that source.
This may be the result of
- uninstalling GitGuardian from the source,
- or excluding the source from the monitored perimeter,
- or a change in your plan that no longer supports this source.
A source that is no longer monitored presents a risk, as no occurrence will be created after a secret has been published in it.
Such a source is identified with a striked shield icon next to it.
No longer monitored sources are no longer listed on the Perimeter page.
Deleted source
A source is considered deleted only when GitGuardian receives evidence of its actual deletion. This means that we don't consider a source deleted just because it has been removed from GitGuardian, but rather only when it has been truly erased. Eg: the repository is deleted on GitHub.
Such a source is identified with a bin icon next to it.
Deleted sources are no longer listed on the Perimeter page.
Source visibility
A source is defined by a visibility scope. Depending of the installed instance, a source can be:
public: anyone with access to the Internet can view the contents of this source. Your secret is publicly exposed and presents a higher security risk.internal(specific to GitLab): internal GitLab projects can be viewed by any authenticated user except external users. Such a GitLab project is identified by a shield icon next to it.private: Only authorized users with access to the source can view its contents. Such a source is identified by a lock icon next to it.
Source criticality
The source criticality feature enables you to assess and assign a level of importance to your monitored sources, helping you prioritize your incidents effectively. This feature allows you to categorize them as low, medium, high, or critical, or leave it unfilled, based on the potential severity of a security incident's impact. Its value depends on the business context of your source, which will be determined by factors such as the nature of the handled data and its connection to resources in a production environment.
How can I add new sources to my protected perimeter?
Version Control Systems
- GitHub integration
- GitHub Enterprise integration
- Gitlab integration
- Bitbucket integration
- Azure DevOps Repos integration
Messaging & ChatOps
Ticketing
Documentation
Troubleshooting connectivity problems
Most often, connectivity problems arise because a firewall, proxy server, corporate network, or other network is configured in a way that blocks GitGuardian.
In case you need to authorize incoming/outgoing connections to/from the SAAS application, this paragraph provides the necessary information.
Allowing GitGuardian's IP addresses
GitGuardian serves the application from the following IP addresses:
- 44.231.207.147/32
- 44.224.13.10/32
- 35.163.105.95/32
- 54.212.233.107/32
- 35.83.131.170/32
- 35.161.89.114/32
These IP addresses are used for:
- VCS integrations (eg: GitHub, GitLab)
- Messaging integrations (eg: Slack, Microsoft Teams)
- Ticketing integrations (eg: Jira Cloud)
- Documentation integrations (eg: Confluence Cloud)
- Alerting integrations (eg: Slack)
Allowing GitGuardian's domains
The following domains are used to expose the application:
- dashboard.gitguardian.com
- hook.gitguardian.com
- api.gitguardian.com
Note: HTTP is only used to redirect to HTTPS.
