Export WAF Logs via SysLog
Problem to solve
WAF users need visibility into the traffic that is passing through the WAF as well as the resulting decision (allow, log, block). Without this visibility, it is difficult to custom tune WAF rules as there is no easy way to verify that the rule is working as designed. The current alternative of SSH'ing into each container to view the logs is inefficient for customers with lots of environments or containers, and provides the information in a format that is difficult to quickly interpret. Ultimately, customers need an easy way to determine whether or not the WAF rules are functioning as designed and to determine what attacks are occurring against the customer's application.
Intended users
Proposal
Although we would like to eventually have Defend logs visible in the GitLab UI, currently it would require a sizable percentage of the Defend engineering team's time to make that possible. Exporting the logs out to a customer's SIEM is the cheapest and fastest path to making the logs available and visible to our customers. For that reason, the proposed implementation of this feature has shifted to focus on building UI that will allow for easy export of logs out to an external SIEM. At some future point in time, we can revisit a path to also make the logs visible in GitLab, as the two are not mutually exclusive.
Note: some customers may choose to send the logs to a central logging solution before forwarding them on to a SIEM. The solution needs to work for this use case as well
Assumption: Nearly all GitLab Ultimate users are running a SIEM
Assumption: The customer will be responsible for ensuring a networking route exists between the SIEM and the deployed environment
- Users will be able to configure and save global settings to have WAF logs exported to a SIEM or Central Logging Solution
- Global settings will be configured on the Settings -> Integration page and will include the following:
- IP address or hostname
- Port
- Protocol (UDP or TCP)
- The format will be JSON format, will be sent via Syslog protocol, and will not be customizable
- The JSON will be sent on one line per message
- Global settings will be applied for all environments where WAF is deployed
- Changes to global settings will be pushed to any environments where WAF is already running
- Syslog messages will be sent from the K8 cluster directly to the specified IP address
Designs
Not Required Functionality
Functionality that is planned for the future but is not required to meet the requirements of this issue include the following:
- The ability to view the logs directly in GitLab will not be considered at this point
Permissions and Security
Permissions should be consistent with the GitLab permission model
Documentation
Documentation for WAF does need to be updated to describe how to configure WAF SIEM settings
Availability & Testing
The following tests will be performed as appropriate:
- Unit tests
- End-to-end tests
- Test with at least one SIEM (Note: Sending via Syslog will make us compatible with 99% of the SIEMs, so testing with just one to confirm connectivity will be adequate)
What does success look like, and how can we measure that?
Success Criteria:
- Users are able to view the logs for their WAF in a SIEM
Acceptance Criteria:
- Latency from the time a log is generated to when it is sent to the SIEM is not greater than one minute
What is the type of buyer?
Technical Discovery
In case there is a need to create a new table (to save the information of the target host), it should have a reference cluster table.
The information save in the DB could used in order to add a second host into ELK custom values. Filebeat documentation is not very clear if this is an elastic search host only or any host. Otherwise we could look into integrating a syslog solution for supporting a wider number of hosts.
A reinstallation of ELK might be required (helm update --install
) or an update of the configmap values-content-configuration-elastic-stack
.