Kong · neethi-shashidhar-kong · Aug 28, 2024
@@ -0,0 +1,126 @@
+---
+title: Set up an audit log destination
+content_type: how-to
+badge: enterprise
+---
+
+You can use the {{site.dev-portal_short_name}} UI or the Audit Logs API to configure destinations for [audit logging](/konnect/org-management/audit-logging/).
+
+## Prerequisites
+
+You must have **Org Admin** or **Portal Admin** permissions to set up audit log destinations for portal.
+
+Before you can push {{site.dev-portal_short_name}} audit logs to an external service, you also need to configure the service to receive logs. 
+This configuration is specific to your vendor.
+
+You can configure a webhook into any application that supports the [ArcSight CEF Format](https://docs.centrify.com/Content/IntegrationContent/SIEM/arcsight-cef/arcsight-cef-format.htm) or raw JSON.
+
+1. Check your SIEM documentation to find out where to send CEF or raw JSON data.
+
+1. In your log collection service, configure a data collection endpoint to push logs to.
+
+1. Take note of the authorization credentials that you need to access this endpoint. {{site.konnect_short_name}} supports any HTTP authorization header type.
+
+1. Configure your firewall settings to allow traffic through the port that you're going to use. 
+See the [Konnect ports and network requirements](/konnect/network/).
+
+## Create a destination
+
+{% navtabs %}
+{% navtab Konnect UI %}
+
+1. From the navigation menu, open {% konnect_icon organizations %} **Organization**, then **Audit Logs Setup** and **Destinations**
+1. Fill in the fields in the **Destinations** tab.
+   * **Region 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.
+    * **Skip SSL Verification**: Skip SSL verification of the host endpoint when delivering payloads.
+
+     {:.note}
+     > We strongly recommend not setting this to `true` as you are subject to man-in-the-middle and other attacks. This option should be considered only when using self-signed SSL certificates in a non-production environment.
+
+{% endnavtab %}
+{% navtab API %}
+
+Now that you have an external endpoint and authorization credentials, you can set up a destination in {{site.konnect_short_name}}.
+
+Create a destination by sending a request to the `/audit-log-destinations` endpoint with the connection details for your SIEM vendor:
+
+```sh
+curl -i -X PATCH https://global.api.konghq.com/v2/audit-log-destinations \
+    --header "Content-Type: application/json" \
+    --header "Authorization: Bearer TOKEN" \
+    --data '{"endpoint":"https://example.com/audit-logs","authorization":"Bearer example-token","log_format":"cef"}'
+```
+
+Replace the following placeholders with your own data:
+* `global.api.konghq.com`: Audit log destinations are global and are available for webhooks in all regions to be used.
+* `TOKEN`: A {{site.dev-portal_short_name}} token
+* `"endpoint":"https://example.com/audit-logs"`: The external endpoint that will receive audit log messages. 
+
+   {:.note}
+    > Check your SIEM documentation to find out where to send CEF data.
+
+* `"authorization":"Bearer example-token"`: 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`.
+* `skip_ssl_verification`: (Optional) Set to `true` to skip SSL verification of the host endpoint when delivering payloads.
+
+  {:.note}
+  > We strongly recommend not setting this to `true` as you are subject to man-in-the-middle and other attacks. This option should be considered only when using self-signed SSL certificates in a non-production environment.
+
+If the request is successful, you will receive a `200` response code, and a response body containing the webhook's configuration details: 
+
+```json
+{
+    "id": "07ec3858-066b-4629-bdc5-d4aa893b424d",
+    "endpoint":"https://example.com/audit-logs",
+    "log_format":"cef",
+    "skip_ssl_verification":false,
+    "updated_at":"2023-04-01T00:00:01Z"
+}
+```
+
+{% endnavtab %}
+{% endnavtabs %}
+
+
+![Audit log webhook](/assets/images/products/konnect/audit-logs/konnect-audit-log-webhook.png)
+
+{% endnavtab %}
+{% navtab API %}
+
+View your audit log destination configuration by running the following command:
+
+```sh
+curl https://global.api.konghq.com/v2/audit-log-destinations \
+    --header "Authorization: Bearer TOKEN"
+```
+
+You will receive a `200` response code and the following data. Note that the `authorization` property is not included in any responses:
+
+```json
+{
+    "id": "07ec3858-066b-4629-bdc5-d4aa893b424d",
+    "endpoint":"https://example.com/audit-logs",
+    "log_format":"cef",
+    "skip_ssl_verification":false,
+    "updated_at":"2023-04-01T00:00:01Z"
+}
+```
+
+
+## More information
+* [Audit logging in {{site.konnect_short_name}}](/konnect/org-management/audit-logging/)
+* [Audit log event reference](/konnect/org-management/audit-logging/reference/)
+* [Set up an audit log replay job](/konnect/org-management/audit-logging/replay-job/)
+* [Verify audit log signatures](/konnect/org-management/audit-logging/verify-signatures/)
+* [Audit Logs API](/konnect/api/audit-logs/latest/)
@@ -0,0 +1,42 @@
+---
+title: Audit Logging in Konnect
+badge: enterprise
+content_type: explanation
+---
+
+Audit logging enables administrators to better spot security risks and maintain compliance of their core infrastructure. 
+
+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.
+
+By tracking {{site.dev-portal_short_name}} audit logs, you gain 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.
+
+## Setting up dev-portal audit logging in {{site.dev-portal_short_name}}
+
+{{site.dev-portal_short_name}} administrators can track streams of security events and operational changes per organization.
+You can do this by [setting up a webhook](/konnect/dev-portal/audit-logging/webhook/) to send data to any 
+log collection service that supports [ArcSight CEF Format](https://docs.centrify.com/Content/IntegrationContent/SIEM/arcsight-cef/arcsight-cef-format.htm) or JSON-formatted data.
+
+Audit logging webhooks can be configured through the {{site.portal_short_name}} **Settings >> Audit Logs Setup** menu, or
+using the [Dev Portal Audit Logs API](/konnect/api/audit-logs/latest/).
+Only {{site.dev-portal_short_name}} org admins and portal admins can configure and view portal audit log webhooks. 
+
+![Audit log webhook](/assets/images/products/konnect/audit-logs/konnect-audit-log-webhook.png)
+
+Audit information includes authentication attempts and authorization requests.
+Each of the audit events contains a trace ID that allows events to be correlated to specific actions. 
+See the [audit log reference](/konnect/org-management/audit-logging/reference/) for details on what is logged.
+
+{:.note}
+> **Note:** You can't customize the events that {{site.dev-portal_short_name}} sends to the logs.
+
+## More information
+* [Set up an audit log destination](/konnect/dev-portal/audit-logging/destination/)
+* [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/dev-portal/audit-logging/reference/)
+* [Verify audit log signatures](/konnect/dev-portal/audit-logging/verify-signatures/)
+* [Dev Portal Audit Logs API](/konnect/api/audit-logs/latest/)
@@ -0,0 +1,216 @@
+---
+title: Audit log reference
+badge: enterprise
+content_type: reference
+---
+
+{{site.dev-portal_short_name}} captures three types of events:
+
+* **Authentication**: Triggered when a user attempts to log into the {{site.dev-portal_short_name}} web application.
+* **Authorization**: Triggered when a permission check is made for a developer against a resource.
+* **Access logs**: Triggered when a request is made to the {{site.dev-portal_short_name}} API.
+
+## Data Retention Period
+{{site.dev-portal_short_name}} retains audit logs for 7 days. 
+
+## Log formats
+
+{{site.dev-portal_short_name}} delivers log events in [ArcSight CEF Format](https://docs.centrify.com/Content/IntegrationContent/SIEM/arcsight-cef/arcsight-cef-format.htm) or JSON. You may specify which format to use in the [audit log destination](/konnect/dev-portal/audit-logging/destination/) endpoint.
+
+Webhook calls include a batch of events. Each event is formatted in either CEF or JSON and separated by a newline. The `Content-Type` is `text/plain`.
+
+To minimize payload size, the message body is compressed. The `Content-Encoding` is `application/gzip`.
+
+All log entries include the following attributes:
+
+Property | Description
+---------|-------------
+Timestamp | Time and date of the event in UTC.
+`rt` | Milliseconds since Unix epoch.
+`src` | The IP address of the request originator.
+`org_id` | The originating organization ID.
+`portal_id` | The originating portal ID.
+`principal_id` | The user ID of the user that performed the action.
+`kong_initiated` | Whether the action was performed by Kong
+`trace_id` | The correlation ID of the request. Use this value to find all log entries for a given request.
+`user_agent` | The user agent of the request: application, operating system, vendor, and version.
+`sig` | An ED25519 signature.
+
+## Authentication logs
+
+Authentication attempts and their outcomes are logged whenever a user logs in to the Dev Portal web application.
+
+Example log entry:
+
+{% navtabs codeblock %}
+{% navtab CEF %}
+```
+2023-05-19T00:03:39Z
+konghq.com CEF:0|ExamplePortal|Dev-Portal|1.0|AUTHENTICATION_OUTCOME_SUCCESS|0|rt=3958q3097698 
+src=127.0.0.1 
+request=/api/v1/authenticate 
+success=true
+org_id=b065b594-6afc-4658-9101-5d9cf3f36b7b
+portal_id=6e04452b-99ce-4bef-ae4f-3e3dc035e070
+principal_id=87655c36-8d63-48fe-9a1e-53b28dfbc19b 
+trace_id=3895213347334635099 
+user_agent=grpc-go/1.51.0
+sig=N_4q2pCgeg0Fg4oGJSfUWKScnTCiC79vq8PIX6Sc_rwaxdWKpVfPwkW45yK_oOFV9gHOmnJBffcB1NmTSwRRDg
+```
+{% endnavtab %}
+{% navtab JSON %}
+```json
+{
+    "cef_version": 0,
+    "event_class_id": "AUTHENTICATION_TYPE_BASIC",
+    "event_product": "Dev-Portal",
+    "event_ts": "2023-05-16T00:28:01Z",
+    "event_vendor": "KongInc",
+    "event_version": "1.0",
+    "name": "AUTHENTICATION_OUTCOME_SUCCESS",
+    "org_id": "b065b594-6afc-4658-9101-5d9cf3f36b7b",
+    "portal_id": "6e04452b-99ce-4bef-ae4f-3e3dc035e070",
+    "principal_id": "87655c36-8d63-48fe-9a1e-53b28dfbc19b",
+    "request": "/api/v1/authenticate",
+    "rt": "1684524079524",
+    "severity": 0,
+    "sig": "N_4q2pCgeg0Fg4oGJSfUWKScnTCiC79vq8PIX6Sc_rwaxdWKpVfPwkW45yK_oOFV9gHOmnJBffcB1NmTSwRRDg",
+    "src": "127.0.0.6",
+    "success": "true",
+    "trace_id": 6891110586028963295,
+    "user_agent": "grpc-node-js/1.8.10"
+}
+```
+{% endnavtab %}
+{% endnavtabs %}
+
+In addition to the defaults, each authentication log entry also contains the following attributes:
+
+Property | Description
+---------|-------------
+`AUTHENTICATION_TYPE` | Can be one of the following: <br> - `AUTHENTICATION_TYPE_BASIC`: basic email and password authentication <br> - `AUTHENTICATION_TYPE_SSO`: authentication with single sign-on (SSO)
+`AUTHENTICATION_OUTCOME` | Can be one of the following: <br> - `AUTHENTICATION_OUTCOME_SUCCESS`: authentication is successful<br> - `AUTHENTICATION_OUTCOME_NOT_FOUND`: user was not found<br> - `AUTHENTICATION_OUTCOME_INVALID_PASSWORD`: invalid password specified
+`success` | `true` or `false`, depending on whether authentication was successful or not.
+
+## Authorization logs
+
+Authorization log entries are created for every permission check in {{site.dev-portal_short_name}}.
+
+Example log entry:
+
+{% navtabs codeblock %}
+{% navtab CEF %}
+```
+2023-05-19T00:03:39Z
+konghq.com CEF:0|ExamplePortal|Dev-Portal|1.0|Dev-Portal|Authz.applications|1|rt=16738287345642 
+src=127.0.0.6 
+action=retrieve 
+granted=true 
+org_id=b065b594-6afc-4658-9101-5d9cf3f36b7b
+portal_id=6e04452b-99ce-4bef-ae4f-3e3dc035e070
+principal_id=87655c36-8d63-48fe-9a1e-53b28dfbc19b 
+actor_id= 
+trace_id=8809518331550410226 
+user_agent=grpc-node/1.24.11 grpc-c/8.0.0 (linux; chttp2; ganges)
+sig=N_4q2pCgeg0Fg4oGJSfUWKScnTCiC79vq8PIX6Sc_rwaxdWKpVfPwkW45yK_oOFV9gHOmnJBffcB1NmTSwRRDg
+```
+{% endnavtab %}
+{% navtab JSON %}
+```json
+{
+    "action": "list",
+    "cef_version": 0,
+    "event_class_id": "Dev-Portal",
+    "event_product": "Dev-Portal",
+    "event_ts": "2023-05-16T00:28:01Z",
+    "event_vendor": "KongInc",
+    "event_version": "1.0",
+    "granted": true,
+    "name": "Authz.applications",
+    "org_id": "b065b594-6afc-4658-9101-5d9cf3f36b7b",
+    "portal_id": "6e04452b-99ce-4bef-ae4f-3e3dc035e070",
+    "principal_id": "87655c36-8d63-48fe-9a1e-53b28dfbc19b",
+    "rt": "1684196881193",
+    "severity": 1,
+    "sig": "N_4q2pCgeg0Fg4oGJSfUWKScnTCiC79vq8PIX6Sc_rwaxdWKpVfPwkW45yK_oOFV9gHOmnJBffcB1NmTSwRRDg",
+    "src": "127.0.0.6",
+    "trace_id": 6891110586028963295,
+    "user_agent": "grpc-node-js/1.8.10"
+}
+```
+{% endnavtab %}
+{% endnavtabs %}
+
+In addition to the defaults, each authorization log entry also contains the following attributes:
+
+Property | Description
+---------|-------------
+`action` | The type of action the user performed on the resource. For example, `retrieve`, `list`, or `edit`.
+`granted` | Boolean indicating whether the authorization was granted or not.
+
+## Access logs
+
+Access logs include information about create, update, and delete requests to the {{site.dev-portal_short_name}} API.
+
+Example log entry:
+
+{% navtabs codeblock %}
+{% navtab CEF %}
+```
+2023-05-16T20:09:54Z 
+konghq.com CEF:0|KongInc|Dev-Portal|1.0|PortalApplication|Ingress|1|rt=1684267794226 
+src=127.0.0.6
+request=/portal-api/api/applications
+act=POST 
+status=200 
+org_id=b065b594-6afc-4658-9101-5d9cf3f36b7b 
+principal_id=87655c36-8d63-48fe-9a1e-53b28dfbc19b 
+user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36 
+trace_id=1146381705542353508 
+query={"end":"1684270800","start":"1684098000"} 
+sig=JxJaQG3Bozrb5WdHE_Y0HaOsim2F1Xsq_bCfk71VgsfldkLAD_SF234cnKNS
+```
+{% endnavtab %}
+{% navtab JSON %}
+```json
+{
+    "act": "POST",
+    "cef_version": 0,
+    "event_class_id": "PortalApplication",
+    "event_product": "Dev-portal",
+    "event_ts": "2023-05-16T00:28:01Z",
+    "event_vendor": "KongInc",
+    "event_version": "1.0",
+    "name": "Ingress",
+    "org_id": "b065b594-6afc-4658-9101-5d9cf3f36b7b",
+    "principal_id": "87655c36-8d63-48fe-9a1e-53b28dfbc19b",
+    "query": "{}",
+    "request": "/portal-api/api/applications",
+    "rt": "1684196881193",
+    "severity": 1,
+    "src": "127.0.0.6",
+    "status": 201,
+    "trace_id": 6891110586028963295,
+    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36",
+    "sig": "N_4q2pCgeg0Fg4oGJSfUWKScnTCiC79vq8PIX6Sc_rwaxdWKpVfPwkW45yK_oOFV9gHOmnJBffcB1NmTSwRRDg",
+}
+```
+{% endnavtab %}
+{% endnavtabs %}
+
+In addition to the defaults, each access log entry also contains the following attributes:
+
+Property | Description
+---------|-------------
+`request` | The endpoint that was called.
+`query` | The request query parameters, if any.
+`act` | The HTTP request method; for example, `POST`, `PATCH`, `PUT`, or `DELETE`.
+`status` | The HTTP response code; for example, `200` or `403`.
+
+
+## See also
+* [Audit logging in {{site.dev-portal_short_name}}](/konnect/dev-portal/audit-logging/)
+* [Set up an audit log webhook](/konnect/dev-portal/audit-logging/webhook/)
+* [Set up an audit log replay job](/konnect/dev-portal/audit-logging/replay-job/)
+* [Verify audit log signatures](/konnect/dev-portal/audit-logging/verify-signatures/)
+* [Audit Logs API](/konnect/api/audit-logs/latest/)