Merge pull request circleci#7532 from circleci/DOCTEAM-814_db_audit-logs

Audit logs

Author: devinmarieb

jekyll/_cci2/audit-logs.adoc

@@ -16,9 +16,9 @@ version:
 == Overview
 CircleCI logs important events in the system for audit and forensic analysis purposes. Audit logs are separate from system logs that track performance and network metrics. 
 
-CircleCI **server customers** can access the audit log feature from the UI in the link:https://app.circleci.com/[web app]. Complete audit logs may be downloaded from the **Audit Log** page within the **Admin** section of the application as a CSV file. Audit log fields with nested data contain JSON blobs.
+CircleCI **server customers**, as well as **Performance and Scale cloud customers**, can access the audit log feature from the UI in the link:https://app.circleci.com/[web app]. Complete audit logs may be downloaded from the **Audit Log** page within the **Admin** section of the application as a CSV file. Audit log fields with nested data contain JSON blobs.
 
-**Cloud customers** can link:https://support.circleci.com/hc/en-us/requests/new[contact CircleCI support] to request an audit log. Only organization admin users can make an audit log request.
+All other cloud customers can link:https://support.circleci.com/hc/en-us/requests/new[contact CircleCI support] to request an audit log. Only organization admin users can make an audit log request.
 
 NOTE: In some situations, the internal machinery may generate duplicate events in the audit logs. The `id` field of the downloaded logs is unique per event and can be used to identify duplicate entries.
 
@@ -63,4 +63,35 @@ The following are the system events that are logged. See `action` in the Field s
 - **version:** Version of the event schema. Currently the value will always be 1. Later versions may have different values to accommodate schema changes.
 - **scope:** If the target is owned by an Account in the CircleCI domain model, the account field should be filled in with the Account name and ID. This data is a JSON blob that will always contain `id` and `type` and will likely contain `name`.
 - **success:** A flag to indicate if the action was successful.
-- **request:** If this event was triggered by an external request this data will be populated and may be used to connect events that originate from the same external request. The format is a JSON blob containing `id` (the unique ID assigned to this request by CircleCI).
+- **request:** If this event was triggered by an external request, this data will be populated and may be used to connect events that originate from the same external request. The format is a JSON blob containing `id` (the unique ID assigned to this request by CircleCI).
+
+== Request audit logs from the web app
+
+CircleCI server customers, as well as cloud customers on the Performance or Scale plan, can request audit logs from the web app. To have access to this feature, cloud customers must be organization admins.
+
+Navigate to **Organization Settings > Security** to view the Audit Log section. Select a date range from the dropdown, then click the **Request audit logs** button. The earliest start date is one year ago from the current day, and the latest end date is the current day. The data available will depend on the data retention period set per organization, so the returned time period for the data could be less than the requested timeframe.
+
+NOTE: Submitted dates are in UTC. To avoid issues arising from potential time zone differences, CircleCI adds extra time to the request. For example, if you request August 2 - August 5, the returned results will be in the range August 1 - August 6. The audit log request column is also displayed in UTC.
+
+=== Audit log status
+
+In the UI, a status request will show the following information:
+
+- Timeframe requested
+- User who made the request
+- Date request was made
+- Expiry date of the request
+- Request status (success, failed, requested)
+
+Successful requests can be active with a download link, active without any data (no download link), or expired (no longer available to download). Successful requests can be downloaded for 10 days.
+
+image::audit-log-request.png[Audit log requests]
+
+Statuses are updated once per hour on the 30-minute mark (for example, 09:30, 10:30, 11:30).
+
+=== Request rate limit
+
+- Performance customers can make one request per 30 day period
+- Scale customers can make three requests per 30 day period
+
+If your organization has reached the maximum amount of requests per 30 days, the audit log request feature will be disabled. If you hover over the disabled **Request audit logs** button, a tooltip will appear displaying the date when new requests can be made. Pending requests count toward the rate limit.

jekyll/_cci2/security-server.adoc

@@ -18,8 +18,6 @@ WARNING: CircleCI Server version 2.x is no longer a supported release. Please co
 
 This document outlines security features built into CircleCI and related integrations.
 
-toc::[]
-
 [#overview]
 == Overview
 Security is our top priority at CircleCI. We are proactive and we act on security issues immediately. Report security issues to [email protected] with an encrypted message using our security team's GPG key (ID: 0x4013DDA7, fingerprint: 3CD2 A48F 2071 61C0 B9B7 1AE2 6170 15B8 4013 DDA7).
@@ -50,7 +48,7 @@ A few different external services and technology integration points touch Circle
 
 [#audit-logs]
 == Audit logs
-The Audit Log feature is only available for CircleCI installed on your servers or private cloud.
+The Audit Log feature is available for CircleCI installed on your servers or private cloud.
 
 CircleCI logs important events in the system for audit and forensic analysis purposes. Audit logs are separate from system logs that track performance and network metrics.
 

jekyll/_cci2/security.md

@@ -3,7 +3,7 @@ layout: classic-docs
 title: "How CircleCI handles security"
 category: [administration]
 description: "An overview of security measures taken at CircleCI."
----
+--- 
 
 This document outlines security initiatives talken by CircleCI.
 

jekyll/_cci2/server/operator/circleci-server-security-features.adoc

@@ -13,8 +13,6 @@ version:
 
 This document outlines security features built into CircleCI and related integrations.
 
-toc::[]
-
 [#security-overview]
 == Overview
 Security is our top priority at CircleCI. We are proactive and we act on security issues immediately. Report security issues to [email protected] with an encrypted message using our security team's GPG key (ID: 0x4013DDA7, fingerprint: 3CD2 A48F 2071 61C0 B9B7 1AE2 6170 15B8 4013 DDA7).
@@ -43,7 +41,7 @@ A few different external services and technology integration points touch Circle
 
 [#audit-logs]
 == Audit logs
-The audit log feature is only available for CircleCI installed on your servers or private cloud.
+The audit log feature is available for CircleCI installed on your servers or private cloud.
 
 CircleCI logs important events in the system for audit and forensic analysis purposes. Audit logs are separate from system logs that track performance and network metrics.