Many are familiar with how GitLab leverages Falco in its Package Hunter project to detect threats through system call monitoring. However, fewer may be aware of a powerful GitLab plugin for Falco that ingests audit events directly from GitLab, transforming them into actionable fields within Falco.
By integrating GitLab audit event fields, you can create Falco rules to detect potential threats in real time and send alerts through your configured notification channels. GitLab provides detailed development guidelines for their real-time audit events.
Configuring audit event streaming
The GitLab plugin acts as a webhook server, making it possible to stream audit events directly into Falco. Once configured as an Audit Event Streaming Destination, GitLab forwards these events to Falco, where they are parsed and evaluated based on predefined rules in the rules/gitlab.yaml file.
Audit Event Streaming Destinations can be configured at either the Group or Instance Level. When configuring at the Instance Level, the server forwards all instance audit events to Falco, providing broader coverage. Conversely, Group-level configuration narrows detections to specific groups. For maximum visibility and threat detection, streaming events at the instance level is recommended.
During the configuration process, GitLab issues a verification token. This token must be added to the falco.yaml configuration file, ensuring Falco can authenticate and validate incoming events.
IP geolocation enrichment for Falco
A standout feature of the plugin is its ability to enrich IP addresses with geolocation data using MaxMind GeoLite (free) or GeoIP2 (commercial) databases. This enrichment adds valuable context to audit events, helping teams detect suspicious activities based on geographical anomalies.
To enable geolocation enrichment:
- Register for the MaxMind databases.
- Download the MaxMind City Database in
.mmdbformat. - Store the database in a location accessible to Falco.
- Configure the database path by specifying the maxmindcitydbpath option in
falco.yaml.
Rule creation
The plugin ships with a variety of default Falco rules, streamlining the detection of malicious events. One example is the detection of unauthorized attempts to access Admin Mode from unfamiliar geographic locations:
- rule: GitLab Admin Mode from unknown country
desc: User failed login by entering wrong password
condition: gitlab.event_type=user_enable_admin_mode and not gitlab.country in (gitlab_known_countries)
output: |
GitLab Admin Mode from unknown country:
-------------------------------------------------------------------------------------------
Event ID: %gitlab.event_id, Event Type: %gitlab.event_type, Created At: %gitlab.created_at
IP Address: %gitlab.ip_address, City: %gitlab.city, Country: %gitlab.country, Country ISO:
%gitlab.countryisocode, Continent: %gitlab.continent
Author ID: %gitlab.author_id, Author Name: %gitlab.author_name, Author Email:
%gitlab.author_email, Author Class: %gitlab.author_class,
Entity ID: %gitlab.entity_id, Entity Type: %gitlab.entity_type, Entity Path:
%gitlab.entity_path
Operation Type: %gitlab.op_type, Operation Item: %gitlab.op_item, Operation Changed From:
%gitlab.op_changed_from, Operation Change To: %gitlab.op_changed_to
Target ID: %gitlab.target_id, Target Type: %gitlab.target_type, Target Details:
%gitlab.target_details
Custom Message: %gitlab.custom_message
Failed Login: %gitlab.failed_login
-------------------------------------------------------------------------------------------
priority: WARNING
source: gitlab
tags: [gitlab, T1098, persistence, privilege-escalation]Code language: YAML (yaml)You can always customize the detection output by incorporating extracted event fields critical for forensics. In the Falco detection rule above, a custom message is included, pulled from a GitLab-specific field. I opted to add arbitrary tagging for MITRE ATT&CK tactic T1098 which is focused on account manipulation to maintain persistence and escalate privileges in GitLab.
Just like the Falco Okta Plugin detects the removal of Multi-Factor Authentication (MFA) in Okta, the GitLab Plugin enables detection of MFA changes for users, which is also important for routine auditing of user access and permissions.
- rule: GitLab - User disabled two-factor authenticaton
desc: User disabled two-factor authenticaton
condition: gitlab.event_type=user_disable_two_factor
output: |
GitLab - User disabled two-factor authenticaton:
-------------------------------------------------------------------------------------------
Event ID: %gitlab.event_id, Event Type: %gitlab.event_type, Created At: %gitlab.created_at
IP Address: %gitlab.ip_address, City: %gitlab.city, Country: %gitlab.country, Country ISO:
%gitlab.countryisocode, Continent: %gitlab.continent
Author ID: %gitlab.author_id, Author Name: %gitlab.author_name, Author Email:
%gitlab.author_email, Author Class: %gitlab.author_class,
Entity ID: %gitlab.entity_id, Entity Type: %gitlab.entity_type, Entity Path:
%gitlab.entity_path
Operation Type: %gitlab.op_type, Operation Item: %gitlab.op_item, Operation Changed From:
%gitlab.op_changed_from, Operation Change To: %gitlab.op_changed_to
Target ID: %gitlab.target_id, Target Type: %gitlab.target_type, Target Details:
%gitlab.target_details
Custom Message: %gitlab.custom_message
Failed Login: %gitlab.failed_login
-------------------------------------------------------------------------------------------
priority: WARNING
source: gitlab
tags: [gitlab, T1556.006, persistence, credentials-access]Code language: YAML (yaml)Conclusion
By adding a plugin to ingest GitLab audit events — similar to the Salesforce Plugin for Falco — security and operations teams can enhance threat detection and response within SaaS environments, all through a unified rule engine. This integration connects host and container security with the code repositories vital to cloud-native workflows, offering comprehensive visibility across distributed systems.
Falco’s GitLab plugin delivers real-time alerts, IP geolocation enrichment, and detailed event parsing, proactively identifying suspicious activities to fortify your security posture. From tracking user actions and administrative changes to detecting unusual login attempts, the integration equips teams to mitigate threats across DevOps pipelines.
For organizations leveraging Falco and GitLab, this plugin seamlessly expands SaaS security coverage, safeguarding the development lifecycle from code to deployment. Discover how Sysdig builds on open-source Falco and its flexible plugin architecture to drive innovation.