-
Notifications
You must be signed in to change notification settings - Fork 594
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(audit): Dev Portal Audit Logging #7816
base: main
Are you sure you want to change the base?
Changes from all commits
ae210a3
3318984
b6d3aa9
693493f
357b2d3
987ba26
2c16a7e
a9b0f7a
08e6e35
c6c51bb
1bed9e9
672f7e5
fe90068
61b1d05
5660766
6f9e56e
60c6f67
b374a8c
d78bc44
3448d01
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
<!-- used in Org Audit Logging Overview and Dev Portal Audit Logging Overview--> | ||
|
||
Audit logs can help you detect and respond to potential security incidents when they occur. Monitoring audit logs proactively can reduce the risk of outages and ensure continuous service for your users. No system can ever be completely secure, but audit logs can be a key part of your incident prevention infrastructure. | ||
|
||
Audit logging provides the following benefits: | ||
* **Security**: System events can be used to show abnormalities to be investigated, forensic information related to breaches, or provide evidence for compliance and regulatory purposes. | ||
* **Compliance**: Regulators and auditors may require audit logs to confirm whether certain certification standards are met. | ||
* **Debugging**: Audit logs can help determine the root causes of efficiency or performance issues. | ||
* **Risk management**: Prevent issues or catch them early. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
<!-- used in Org Audit Logging Set Up Webhook and Dev Portal Audit Logging Set Up Webhook--> | ||
Webhooks are triggered via an HTTPS request using the following retry rules: | ||
|
||
- Minimum retry wait time: 1 second | ||
- Maximum retry wait time: 30 seconds | ||
- Maximum number of retries: 4 | ||
|
||
A retry is performed on a connection error, server error (`500` HTTP status code), or too many requests (`429` HTTP status code). | ||
|
||
{% if include.desc == "Dev Portal" %} | ||
{:.note} | ||
> **Note:** Currently, Dev Portal audit logs only support authentication logs, which are triggered when a user logs in to Dev Portal. | ||
{% endif %} | ||
|
||
## Prerequisites | ||
|
||
A SIEM provider that supports the [ArcSight CEF Format](https://docs.centrify.com/Content/IntegrationContent/SIEM/arcsight-cef/arcsight-cef-format.htm) or raw JSON. | ||
|
||
## Configure your SIEM provider | ||
|
||
Before you can push audit logs to your SIEM provider, configure the service to receive logs. | ||
This configuration is specific to your vendor. | ||
|
||
1. In your log collection service, configure an HTTPS data collection endpoint you can send CEF or raw JSON data logs to. {{site.konnect_short_name}} supports any HTTP authorization header type. Save the endpoint URL, this will be used later in {{site.konnect_short_name}}. | ||
|
||
1. Create and save an access key from your SIEM provider. | ||
|
||
1. Configure your network's firewall settings to allow traffic through the `8071` TCP or UDP port that {{site.konnect_short_name}} uses for audit logging. | ||
See the [Konnect ports and network requirements](/konnect/network/). |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
--- | ||
title: Audit Logging in Dev Portal | ||
content_type: concept | ||
--- | ||
|
||
Dev Portal audit logs are set up and managed separately from org-wide {{site.konnect_short_name}} audit logs. For more information about how to configure audit logging for {{site.konnect_short_name}}, see [Set up an audit log webhook for Dev Portal](/konnect/dev-portal/audit-logging/webhook/). | ||
|
||
{% include_cached /md/konnect/audit-logging/audit-log-overview.md %} | ||
|
||
## More information | ||
* [Set up an portal audit log webhook](/konnect/dev-portal/audit-logging/webhook/) | ||
* [Set up an portal audit log replay job](/konnect/dev-portal/audit-logging/replay-job/) | ||
* [Portal Audit log event reference](/konnect/reference/audit-logs/) | ||
* [Verify audit log signatures](/konnect/reference/verify-signatures/) | ||
* [Dev Portal Audit Logs API](/konnect/api/audit-logs/latest/) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,107 @@ | ||
--- | ||
title: Set up an audit log replay job | ||
content_type: how-to | ||
--- | ||
|
||
You can use the {{site.dev-portal_short_name}} Audit Logs API to configure replay jobs for [audit logging](/konnect/dev-portal/audit-logging/). | ||
|
||
Replay jobs are useful when you have missed audit log entries due to an error or a misconfigured audit | ||
log webhook. You may have one replay job at a time per region, and request data from up to one week ago. | ||
A replay job in a region will resend data for the requested timeframe to the webhook configured for that region. | ||
|
||
## Prerequisites | ||
|
||
* [Org Admin or Portal Admin permissions](/konnect/org-management/teams-and-roles/teams-reference/) | ||
* Your [audit log webhook](/konnect/dev-portal/audit-logging/webhook/) must be enabled and ready to receive data. | ||
|
||
|
||
## Configure a replay job | ||
|
||
{% navtabs %} | ||
{% navtab Konnect UI %} | ||
|
||
1. In {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal), click the Dev Portal you want to configure a replay job for. | ||
1. Click **Settings** in the sidebar, and then click the **Audit Logs** tab. | ||
1. Click the **Replay** tab. | ||
1. Choose a timeframe for which you want to replay the logs. | ||
|
||
You can choose one of the preset relative increments for up to 24 hours, or | ||
set a custom timeframe for up to 7 days. | ||
|
||
1. Apply the timeframe, then click **Send Replay**. | ||
|
||
{% endnavtab %} | ||
{% navtab API %} | ||
|
||
Configure the replay job for a region by sending a `PUT` request to the [`/audit-log-replay-job`](/konnect/api/portal-management/latest/) endpoint: | ||
|
||
```sh | ||
curl -i -X PUT https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-replay-job \ | ||
--header "Content-Type: application/json" \ | ||
--header "Authorization: Bearer <personal-access-token>" \ | ||
--data '{ | ||
"start_at": "2023-03-27T20:00:00Z", | ||
"end_at": "2023-03-27T20:00:00Z" | ||
}' | ||
``` | ||
|
||
Be sure to replace the following placeholder values: | ||
* `{region}.api.konghq.com`: The region your portal is located in. Can be `us`, `ap`, or `eu`. | ||
* `{portalId}`: The ID of the Dev Portal with your webhook. | ||
* `<personal-access-token>`: Your {{site.konnect_short_name}} [personal access token (PAT)](/konnect/api/#authentication). | ||
* `start_at` and `end_at`: Specify the timeframe for which you want to receive audit log events. `start_at` must be no more than seven days ago. | ||
|
||
If the request is successful, you will receive a `202` response code and a response body containing the replay job details. | ||
|
||
{% endnavtab %} | ||
{% endnavtabs %} | ||
|
||
## View replay job | ||
|
||
{% navtabs %} | ||
{% navtab Konnect UI %} | ||
|
||
1. In {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal), click the Dev Portal you want to view the replay job for. | ||
1. Click **Settings** in the sidebar, then click the **Audit Logs** tab. | ||
1. Click the **Replay** tab. | ||
1. Check the status table below the configuration field. | ||
|
||
{% endnavtab %} | ||
{% navtab API %} | ||
|
||
You can view the audit log replay job in a given region by issuing a GET request to the [`audit-log-replay-job`](/konnect/api/portal-management/latest/) endpoint: | ||
|
||
```sh | ||
curl -i -X GET https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-replay-job \ | ||
--header "Authorization: Bearer <personal-access-token>" | ||
``` | ||
|
||
Be sure to replace the following placeholder values: | ||
* `{region}.api.konghq.com`: The region your portal is located in. Can be `us`, `ap`, or `eu`. | ||
* `{portalId}`: The ID of the Dev Portal with your webhook. | ||
* `<personal-access-token>`: Your {{site.konnect_short_name}} [personal access token (PAT)](/konnect/api/#authentication). | ||
|
||
You will receive a `200` response code and the job details. | ||
|
||
{% endnavtab %} | ||
{% endnavtabs %} | ||
|
||
## Replay job status | ||
|
||
A replay job can be in one of the following statuses: | ||
|
||
| Status | Description | | ||
| -------|-------------| | ||
| `unconfigured` | Initial state. The job has not been set up. | | ||
| `accepted` | The job has been accepted for scheduling. | | ||
| `pending` | The job has been scheduled. | | ||
| `running` | The job is in progress. When a replay job is `running`, a request to update the job will return a `409` response code until it has completed or failed. | | ||
| `completed` | The job has finished with no errors. | | ||
| `failed` | The job has failed. | | ||
|
||
## More information | ||
* [Audit logging in {{site.konnect_short_name}}](/konnect/dev-portal/audit-logging/) | ||
* [Set up an audit log webhook](/konnect/dev-portal/audit-logging/webhook/) | ||
* [Audit log event reference](/konnect/reference/audit-logs/) | ||
* [Verify audit log signatures](/konnect/reference/verify-signatures/) | ||
* [Audit Logs API](/konnect/api/audit-logs/latest/) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,140 @@ | ||
--- | ||
title: Set up an audit log webhook for Dev Portal | ||
content_type: how-to | ||
--- | ||
|
||
You can use the {{site.konnect_short_name}} UI or the [Audit Logs](/konnect/api/audit-logs/latest/) and [Portal Management](/konnect/api/portal-management/latest/) APIs to configure webhooks for [audit logging](/konnect/dev-portal/audit-logging/). | ||
|
||
{% include_cached /md/konnect/audit-logging/webhook-overview-prereq-siem-config.md desc='Dev Portal' %} | ||
|
||
|
||
## Create a webhook | ||
|
||
{% navtabs %} | ||
{% navtab Konnect UI %} | ||
Before you configure the webhook, you must first create an audit log destination. This allows you to set your audit log destination (the endpoint URL for your SIEM provider) and reuse it. | ||
|
||
1. From {% konnect_icon organizations %} [**Organization**](https://cloud.konghq.com/organization) in the sidebar, click **Audit Logs Setup**. | ||
1. On the **Webhook Destination** tab, click **New Webhook** and configure the following: | ||
* **Name**: The name you want to display for the audit log destination. | ||
* **Endpoint**: The external endpoint that will receive audit log messages. | ||
* **Authorization Header**: The authorization type and credential to pass to your log collection endpoint. | ||
{{site.konnect_short_name}} will send this string in the `Authorization` header of requests to that endpoint. | ||
|
||
For example, if you are setting up the webhook for Splunk, you could provide a Splunk access token: | ||
`"authorization":"Splunk example-token12234352535235"`. | ||
|
||
* **Log Format**: The output format of each log message. Can be CEF or JSON. | ||
* **Disable SSL Verification**: Disables SSL verification of the host endpoint when delivering payloads. We recommend disabling SSL verification only when using self-signed SSL certificates in a non-production environment as this can subject you to man-in-the-middle and other attacks. | ||
1. To configure the Dev Portal audit log webhook, navigate to {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal) in the sidebar. | ||
1. Click the Dev Portal you want to configure the webhook for and then click **Settings**. | ||
1. Click the **Audit Logs** tab. | ||
1. Enable the webhook and then select the SIEM provider endpoint from the **Endpoint** drop down menu. You can't customize the events that {{site.konnect_short_name}} sends to the logs. | ||
1. Click **Save**. | ||
|
||
{% endnavtab %} | ||
{% navtab API %} | ||
|
||
Now that you have an external endpoint and authorization credentials, you can set up an audit log destination in {{site.konnect_short_name}}. The `/audit_log_destinations` endpoint allows you to set your audit log destination, which includes the endpoint URL and access key for your SIEM provider, and reuse it. | ||
|
||
1. Create an audit log destination by sending a request to the [`/audit-log-destinations`](/konnect/api/audit-logs/latest/) endpoint with the connection details for your SIEM provider: | ||
|
||
```sh | ||
curl -i -X POST https://global.api.konghq.com/v2/audit-log-destinations \ | ||
--header "Content-Type: application/json" \ | ||
--header "Authorization: Bearer <personal-access-token>" \ | ||
--data '{ | ||
"endpoint": "https://example.com/audit-logs", | ||
"authorization": "<SIEM-access-token>", | ||
"log_format": "cef", | ||
"name": "example destinations name" | ||
}' | ||
``` | ||
|
||
Be sure to replace the following placeholder values: | ||
* `<personal-access-token>`: Your {{site.konnect_short_name}} [personal access token (PAT)](/konnect/api/#authentication). | ||
* `endpoint`: The external endpoint that will receive audit log messages. Check your SIEM documentation to find out where to send CEF or JSON data. | ||
* `authorization`: The authorization type and credential to pass to your log collection endpoint. | ||
{{site.konnect_short_name}} will send this string in the `Authorization` header of requests to that endpoint. For example, if you are setting up the webhook for Splunk, you could provide a Splunk access token: `"authorization":"Splunk example-token12234352535235"`. | ||
* `log_format`: The output format of each log message. Can be `cef` or `json`. | ||
* `name`: A unique human-readable name to identify this destination. | ||
* `skip_ssl_verification`: (Optional) Set to `true` to skip SSL verification of the host endpoint when delivering payloads. We recommend skipping SSL verification only when using self-signed SSL certificates in a non-production environment as this can subject you to man-in-the-middle and other attacks. | ||
|
||
If the request is successful, you will receive a `200` response code, and a response body containing the audit log destination's configuration details. Be sure to save the audit log destination `id` for the next step. | ||
|
||
1. Create a webhook by sending a PATCH request to the [`/audit-log-webhook`](/konnect/api/portal-management/latest/) endpoint with your configured audit log destination: | ||
|
||
```sh | ||
curl -i -X PATCH https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-webhook \ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks! I added it now |
||
--header "Content-Type: application/json" \ | ||
--header "Authorization: Bearer <personal-access-token>" \ | ||
--data '{ | ||
"audit_log_destination_id": "05atf3f2-9d07-4e46-8115-c58ca594d00e", | ||
"enabled": true | ||
}' | ||
``` | ||
|
||
Be sure to replace the following placeholder values: | ||
* `{region}.api.konghq.com`: The region your Dev Portal is located in. Can be `us`, `au`, or `eu`. | ||
* `<personal-access-token>`: Your {{site.konnect_short_name}} [personal access token (PAT)](/konnect/api/#authentication). | ||
* `{portalId}`: The ID of the Dev Portal with your webhook. | ||
* `audit_log_destination_id`: The ID of the audit log destination that you want to use. | ||
|
||
You can't customize the events that {{site.konnect_short_name}} sends to the logs. | ||
|
||
If the request is successful, you will receive a `200` response code, and a response body containing the webhook's configuration details. | ||
|
||
{% endnavtab %} | ||
{% endnavtabs %} | ||
|
||
Your webhook should now start receiving audit logs. | ||
|
||
## View audit log webhook status | ||
|
||
{% navtabs %} | ||
{% navtab Konnect UI %} | ||
|
||
1. In {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal), click the Dev Portal you want to view the webhook status job for. | ||
1. Click **Settings** in the sidebar, then click the **Audit Logs** tab. | ||
1. Click the **Status** tab. | ||
|
||
A badge will display next to the title of the webhook with the status of the webhook. | ||
|
||
To see the last attempt timestamp and the last response code, use the [audit log API](/konnect/api/audit-logs/latest/). | ||
|
||
{% endnavtab %} | ||
{% navtab API %} | ||
|
||
View your audit log webhook status by sending a GET request to the [`/audit-log-webhook/status`](/konnect/api/portal-management/latest/) endpoint: | ||
|
||
```sh | ||
curl -i -X GET https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-webhook/status \ | ||
--header "Authorization: Bearer <personal-access-token>" | ||
``` | ||
|
||
Be sure to replace the following placeholder values: | ||
* `{region}.api.konghq.com`: The region your Dev Portal is located in. Can be `us`, `au`, or `eu`. | ||
* `<personal-access-token>`: Your {{site.konnect_short_name}} [personal access token (PAT)](/konnect/api/#authentication). | ||
* `{portalId}`: The ID of the Dev Portal with your webhook. | ||
|
||
You will receive a `200` response code and a response body with information about the webhook status: | ||
|
||
```json | ||
{ | ||
"last_attempt_at": "2023-04-04T18:11:16Z", | ||
"last_response_code": 200, | ||
"webhook_enabled": true, | ||
"webhook_status": "active" | ||
} | ||
``` | ||
|
||
{% endnavtab %} | ||
{% endnavtabs %} | ||
|
||
|
||
## More information | ||
* [Audit logging in {{site.konnect_short_name}}](/konnect/dev-portal/audit-logging/) | ||
* [Audit log event reference](/konnect/reference/audit-logs/) | ||
* [Set up an audit log replay job](/konnect/dev-portal/audit-logging/replay-job/) | ||
* [Verify audit log signatures](/konnect/reference/verify-signatures/) | ||
* [Audit Logs API](/konnect/api/audit-logs/latest/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can we replace the screenshots here for "View audit log webhook status" to the screenshots for Dev Portal once that is available? The status will be available under Audit Logs Setup under Organization as well as in Dev Portal.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@smritikjaggi Good call out! I'll revisit the screenshots
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I decided to omit screenshots since we were only using them to highlight the status badge. And I thought it would be easy enough to explain to a user where to find the status badge instead of having a screenshot.