Skip to content
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

Draft
wants to merge 20 commits into
base: main
Choose a base branch
from

Conversation

alexgervais
Copy link
Contributor

@alexgervais alexgervais commented Aug 29, 2024

Description

Resolving conflicts from #7803
Adds documentation for dev portal audit logging

DOCU-4044

Testing instructions

Preview link:

Checklist

@alexgervais alexgervais requested a review from a team as a code owner August 29, 2024 18:03
Copy link

netlify bot commented Aug 29, 2024

Deploy Preview for kongdocs ready!

Name Link
🔨 Latest commit 3448d01
🔍 Latest deploy log https://app.netlify.com/sites/kongdocs/deploys/6709560df5598e00088f7706
😎 Deploy Preview https://deploy-preview-7816--kongdocs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
9 paths audited
Performance: 92 (🟢 up 2 from production)
Accessibility: 92 (no change from production)
Best Practices: 98 (🟢 up 8 from production)
SEO: 91 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

@cloudjumpercat cloudjumpercat self-assigned this Sep 6, 2024
@cloudjumpercat cloudjumpercat added do not merge Issues/ PRs whose changes should not be merged at this time review:copyedit Request for writer review. labels Sep 13, 2024
@cloudjumpercat cloudjumpercat marked this pull request as draft September 13, 2024 19:31
cloudjumpercat and others added 2 commits September 13, 2024 15:50
…l overview use case table, add link to audit log on create dev portal, start revising some of the content

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
@cloudjumpercat cloudjumpercat mentioned this pull request Sep 18, 2024
2 tasks
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
…inks to the new redirects

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
…g audit log UI

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Copy link
Contributor

@smritikjaggi smritikjaggi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Left some comments...

content_type: concept
---

{% include_cached /md/konnect/audit-logging/audit-log-overview.md %}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this line inherits the text from Audit Logs for Enterprise. However, can we modify this line from By tracking Konnect audit logs, you gain the following benefits to By tracking Dev Portal audit logs, you gain the following benefit?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I edited this so it's a bit more generic, like "By tracking audit logs..." so it would apply to both. Currently, I don't know of a way to make that bit specific to the feature area and still reuse for both pages. I wanted to reuse it because 99% of the content was the exact same, so it helps us keep both up-to-date and reduce translation costs in the future.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can create conditional includes here is a random example

{% include_cached /md/konnect/audit-logging/audit-log-overview.md %}

{:.note}
> **Note:** 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 a {{site.konnect_short_name}}, see [Set up an audit log webhook for Dev Portal](/konnect/dev-portal/audit-logging/webhook/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the intent here to navigate users looking to configure audit logging for Konnect to https://docs.konghq.com/konnect/org-management/audit-logging/?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smritikjaggi Yep! I added one to the org management audit logging page as well. This is just to help users who maybe landed here on a search accidentally know that the configurations are different and direct them to the correct doc.

You can use the {{site.konnect_short_name}} UI or the Audit Logs API to configure webhooks for [audit logging](/konnect/dev-portal/audit-logging/).

{:.note}
> **Note:** Currently, Dev Portal audit logs only support authorization logs, which are triggered when a user logs in to Dev Portal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently, Dev Portal audit logs only support authentication logs. Authorization logs are in scope for future milestones.

{:.note}
> **Note:** Currently, Dev Portal audit logs only support authorization logs, which are triggered when a user logs in to Dev Portal.

{% include_cached /md/konnect/audit-logging/webhook-overview-prereq-siem-config.md %}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we modify the sentence Before you can push Konnect audit logs to an external service to Before you can push Dev Portal audit logs to an external service.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think users will get confused by the term "external service"? We could say - "Before you can push Dev Portal Audit Logs to a SEIM system of choice"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I edited it so it's a bit more generic so it applies to both Dev Portal and Konnect and changes "external service" to SIEM provider.

* **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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we replace "this" to "skip SSL verification":
We strongly recommend not setting "skip SSL Verification" to true


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.

The {{site.konnect_short_name}} API uses [Personal Access Token (PAT)](/konnect/api/#authentication) authentication. You can obtain your PAT from the [personal access token page](https://cloud.konghq.com/global/account/tokens). The PAT must be passed in the `Authorization` header of all requests.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not see this section in the deploy preview - am I missing something?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smritikjaggi This will be under the API tab

Screenshot 2024-09-24 at 3 13 13 PM


## Prerequisites

* [**Org Admin** or **Portal Admin** permissions](/konnect/org-management/teams-and-roles/teams-reference/)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@neethi-shashidhar-kong - can you confirm if we would have Portal Admin role set up audit logs for Dev Portal based on the perm sync conversations this morning? I think only Org Admin will have permissions.

{% navtabs %}
{% navtab Konnect UI %}

1. From the navigation menu, open {% konnect_icon Dev-Portal %} **Settings**, then **Audit Logs Setup**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first time I read this, I did not realize we are looking at Settings under Dev Portal menu. Would it be helpful to clarify that?

{% navtabs %}
{% navtab Konnect UI %}

1. From the navigation menu, open {% konnect_icon Dev-Portal %} **Settings**, then **Audit Logs Setup**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first time I read this, I did not realize we are looking at Settings under Dev Portal menu. Would it be helpful to clarify that?

@@ -35,7 +90,7 @@ Timestamp | Time and date of the event in UTC.
`user_agent` | The user agent of the request: application, operating system, vendor, and version.
`sig` | An ED25519 signature.

## Authentication logs
### Authentication logs

Authentication attempts and their outcomes are logged whenever a user logs in to the Konnect application or uses the Konnect API.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Authentication attempts and their outcomes are logged whenever a user logs in to the Konnect application or a Dev Portal either through the UI or the API.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Fixed this in my revision.

Copy link
Contributor Author

@alexgervais alexgervais left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! 🙌

1. Create a webhook by sending a PATCH request to the `/audit-log-webhook` endpoint with your configured audit log destination:

```sh
curl -i -X PATCH https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-webhook \
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The {portalId} placeholder is not documented bellow. For other requests it appears to be documented (example). I feel we should be consistent, even if repetitive

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I added it now

{% navtabs codeblock %}
{% navtab CEF %}
```
Apr 14 05:39:08 konghq.com CEF:0|KongInc|Konnect|1.0|konnect|Authz.usage|1|rt=1681450748406 src=127.0.0.6 action=retrieve granted=true org_id=b065b594-6afc-4658-9101-5d9cf3f36b7b principal_id=87655c36-8d63-48fe-9a1e-53b28dfbc19b trace_id=3895213347334635099 user_agent=grpc-node/1.24.11 grpc-c/8.0.0 (linux; chttp2; ganges)
Copy link
Contributor Author

@alexgervais alexgervais Sep 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The format differs slightly for DevPortal audit logs. This example represents what one might expect from a Konnect Org audit log, but I feel we should have example of DevPortal logs too and document the extra portal_id field.

I tried to capture the difference in a previous commit: b6d3aa9#diff-6c4dc5b26f5a4395618ddcf396cfbad8ceb081df139f65907ad604e85b52b519R104-R134

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call! I added them back in the revision with a tab for the Konnect logs and a tab for the Dev Portal logs

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
@cloudjumpercat
Copy link
Contributor

@smritikjaggi @alexgervais Thanks for the feedback! I responded to any questions/comments you had and implemented your feedback. I still haven't revised the Dev Portal audit log UI instructions since I'm waiting for internal release for those.

Feel free to look things over again or I'll reach out after I've revised the UI instructions after internal release so you can review everything. I'll be sending this out for a writer review for either the end of this week or early next week.

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Comment on lines 99 to 102
You can view the status of your webhook through the **Audit Logs Setup** page under
{% konnect_icon organizations %} **Organization**. 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.
Copy link
Contributor

@cloudjumpercat cloudjumpercat Oct 2, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Team Docs writers: UI instructions need an update here

Comment on lines 24 to 31
1. In {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal), click **Settings**, and then click **Audit Logs Setup**.
1. Switch to 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**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Team Docs writers: UI instructions need an update here

Comment on lines 73 to 78
1. In {% konnect_icon dev-portal %} [**Dev Portal**](https://cloud.konghq.com/portal), click **Settings**, then **Audit Logs Setup**.
1. Switch to the **Replay** tab.
1. Check the status table below the configuration field.

![Audit log replay](/assets/images/products/konnect/audit-logs/konnect-audit-log-replay.png)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Team Docs writers: UI instructions need an update here

@cloudjumpercat
Copy link
Contributor

Items left for a writer to do:

  • Several Dev Portal audit log UI flows need to be revised and tested. I've marked them with comments in the PR.
  • The whole thing need a copyedit/writer review.

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Comment on lines +41 to +49
1. Remove the signature (the `sig` value) from the audit log, but be sure to save the signature to decode later.

The adjusted entry will look slightly different depending on the format that you're using. The following {{site.konnect_short_name}} org audit log examples show what the entry will look like in each format after removing the signature:

{% navtabs codeblock %}
{% navtab CEF %}
```
Apr 14 05:39:08 konghq.com CEF:0|KongInc|Konnect|1.0|konnect|Authz.usage|1|rt=1681450748406 src=127.0.0.6 action=retrieve granted=true org_id=b065b594-6afc-4658-9101-5d9cf3f36b7b principal_id=87655c36-8d63-48fe-9a1e-53b28dfbc19b trace_id=3895213347334635099 user_agent=grpc-node/1.24.11 grpc-c/8.0.0 (linux; chttp2; ganges)
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For writer review: Could I get formatting help here? This isn't rendering correctly in the preview.

{% include_cached /md/konnect/audit-logging/audit-log-overview.md %}

{:.note}
> **Note:** 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/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about not having this be a note? I think it might fit nice before the include, like an intro to the include.

Comment on lines 11 to 13
> **Notes:**
* Only supports HTTPS Webhook endpoints.
* You can't customize the events that {{site.konnect_short_name}} sends to the logs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this makes a bit more sense in the create a web hook step. Then the text above it isnt sandwiched by admonitions
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would move the top admonition to where this one is. Starting a doc with a note that high up makes me feel like a feature is incomplete or broken.

* `completed`: The job has finished with no errors.
* `failed`: The job has failed.

When a replay job is `running`, a request to update the job will return a `409` response code until it has completed or failed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you choose not to use a table, I would put this as a secondary bullet under running

app/konnect/reference/verify-signatures.md Outdated Show resolved Hide resolved
app/konnect/reference/verify-signatures.md Outdated Show resolved Hide resolved
{% endnavtab %}
{% endnavtabs %}

1. Decode the signature and public key into bytes. Both the signature and the public key are Base64 URL-encoded.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is how to decode relevant to this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll ask!

Comment on lines 81 to 90
## See also
* Dev Portal audit logs:
* [Audit logging in Dev Portal](/konnect/dev-portal/audit-logging/)
* [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/)
* Global {{site.konnect_short_name}} audit logs:
* [Audit logging in {{site.konnect_short_name}}](/konnect/org-management/audit-logging/)
* [Set up an audit log webhook](/konnect/org-management/audit-logging/webhook/)
* [Set up an audit log replay job](/konnect/org-management/audit-logging/replay-job/)
* [Audit Logs API](/konnect/api/audit-logs/latest/)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The formatting feels off here for me but I think you can just leave it -- the information is what matters more.

cloudjumpercat and others added 2 commits October 9, 2024 15:35
Co-authored-by: Angel <Guaris@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Copy link
Contributor

@Guaris Guaris left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dont think this should be enterprise maybe no badge https://konghq.com/pricing

@@ -0,0 +1,16 @@
---
title: Audit Logging in Dev Portal
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

I don't think this makes sense anymore but if it does leave it

---
title: Set up an audit log replay job
content_type: how-to
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

---
title: Set up an audit log webhook for Dev Portal
content_type: how-to
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

@@ -1,41 +1,16 @@
---
title: Audit Logging in Konnect
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

---
title: Verify audit log signatures
content_type: how-to
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

@@ -1,48 +1,20 @@
---
title: Set up an audit log webhook
title: Set up an audit log webhook for a Konnect org
content_type: how-to
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

@@ -4,16 +4,15 @@ content_type: how-to
badge: enterprise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badge: enterprise

Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
do not merge Issues/ PRs whose changes should not be merged at this time review:copyedit Request for writer review.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants