Refactor audit log documentation to enhance clarity on viewing, exporting, and accessing logs via API

Author: wolz-CODElife

learn-pr/github/manage-sensitive-data-security-policies/includes/2-set-security-policies.md

@@ -147,91 +147,3 @@ Organization policies and enterprise policies set governance, access, and workfl
 
 Any enterprise-level policy in “Your enterprises > Policies > Repository policies” overrides org-level settings under Settings > Member privileges.
 
-## GitHub Audit Log APIs
-
-Use REST or GraphQL to investigate missing assets and monitor security events.
-
-### Steps to Investigate Missing Assets
-1. Identify the asset (e.g., repo, team, member).
-2. Query the audit log API (`repository.deleted`, etc.).
-3. Filter by event type.
-4. Review metadata for actor and timestamp.
-5. Take corrective actions.
-
-**Example REST request:**
-```http
-GET /orgs/{org}/audit-log?phrase=repository.deleted
-Authorization: Bearer YOUR-TOKEN
-```
-
-**Example GraphQL query:**
-```graphql
-query {
-  auditLogEntries(first: 10, query: "repository.deleted") {
-    nodes {
-      action
-      actor { login }
-      createdAt
-    }
-  }
-}
-```
-
-### Use Cases for Audit Logs
-- Investigate security incidents.
-- Monitor compliance.
-- Track changes to repos, users, and settings.
-- Detect unauthorized access.
-
-### Audit Log Streaming
-Stream logs to SIEM tools (Splunk, Datadog) or storage (AWS S3, Azure Event Hubs) for real-time monitoring and long-term retention.
-
-### Git and API Activity Logs
-Monitoring Git and API activity logs is crucial for maintaining the security and integrity of your repositories. These logs provide visibility into user actions, enabling you to detect unauthorized access, investigate incidents, and ensure compliance with organizational policies.
-
-- **Git activity:** `git.push`, `pull_request`, etc.
-- **API activity:** `api.request`, include source IP for threat detection.
-
-### Additional Events (EMUs)
-Enterprise Managed Users add events like `user.login`, `repository.permissions_updated`, `repository.forked`.
-
-### Filtering by Token
-Query `?phrase=token` to find token-related actions and detect misuse.
-
-## Key Security Features of a GitHub Repository
-- **SECURITY.md:** Define reporting and supported versions.
-- **Branch Protection:** Enforce reviews, status checks, and commit signing.
-- **Dependabot Alerts:** Automatic vulnerability detection and updates.
-- **Code Scanning:** Continuous analysis via CodeQL.
-- **Secret Scanning & Push Protection:** Real-time prevention and alerts.
-- **Security Advisories:** Draft, collaborate, and publish advisories.
-- **Dependency Graph:** Visualize and audit dependencies.
-- **2FA & RBAC:** Enforce strong authentication and least privilege.
-- **Audit Logs:** Monitor, filter, and export logs for compliance.
-
-## API Access and Integrations
-| **Token Type**            | **Description** |
-|----------------------------|---------------------------|
-| **Personal Access Tokens (PATs)** | Tokens tied to a user account for API access. |
-| **Installation Tokens**    | Tokens generated for GitHub Apps installations with fine-grained permissions.  |
-| **OAuth Tokens** | Tokens used for OAuth app authentication and API access. |
-| **Device Tokens** | Tokens used for device-based authentication flows. |
-| **Refresh Tokens** | Tokens used to renew expired access tokens without re-authentication. |
-
-| **Rate Limit Type**        | **Limit**  |
-|--------------------------|---------------------|
-| **Unauthenticated**        | 60 requests per hour. |
-| **Authenticated**          | 5000 requests per hour. |
-| **Apps**                   | Varies by installation, depending on the app's configuration.|
-
-**Check via API:**
-```sh
-curl -H "Authorization: token YOUR_TOKEN" \
-     -H "Accept: application/vnd.github.v3+json" \
-     https://api.github.com/rate_limit
-```
-
-GitHub Apps offer fine-grained permissions and are ideal for organizational integrations, while Personal Access Tokens (PATs) are simpler and tied to user accounts, making them suitable for basic scripts but with less control. OAuth Apps should be granted the least privilege scopes, with event subscriptions managed and reviewed regularly. Organizations can restrict untrusted apps through settings to enhance security.
-
-Enterprise Managed Users (EMUs) provide managed accounts with limited scope, ensuring compliance and control. Data residency policies help organizations store logs and data in specified regions, aligning with regulatory requirements. API usage should adhere to organizational policies and residency guidelines to maintain compliance.
-

learn-pr/github/manage-sensitive-data-security-policies/includes/4-report-log.md

@@ -18,7 +18,7 @@ Your organization’s audit log records actions taken by organization members. A
 > [!NOTE]
 > Logs are retained for up to 90 days in GitHub Enterprise Cloud (120 days via GraphQL on Enterprise Server).
 
-## Viewing Audit Logs in the GitHub UI
+## Viewing and Exporting Audit Logs via the GitHub UI
 
 1. On GitHub.com, navigate to your organization’s **Settings > Audit log**.  
 2. Use the **Filters** field to narrow results by qualifier (actor, repo, action, date).  
@@ -35,15 +35,24 @@ Your organization’s audit log records actions taken by organization members. A
 | `repo`    | octo-org/documentation          |
 | `created` | 2019-06-01                      |
 
-## Accessing Audit Logs via APIs
+## Accessing Audit Logs via API
+
+### REST API
+
+- **Scope:** Enterprise Cloud (up to 90 days; Git events for 7 days).  
+- **Monitors:** Settings changes, permission updates, team membership, application changes, plus Git events (push, pull, merge).  
+
+```http
+GET /orgs/{org}/audit-log?phrase=git.push
+Authorization: Bearer YOUR_TOKEN
+```
 
 ### GraphQL API
 
 - **Scope:** Enterprise Server (up to 120 days).  
 - **Monitors:** Settings changes, permission updates, team membership, application changes.  
 - **Limitations:** Does _not_ include Git events (pushes, pulls).  
 
-**Sample Query:**
 ```graphql
 query {
   auditLogEntries(first: 20, query: "org:octo-org action:repo.cleanup") {
@@ -57,28 +66,16 @@ query {
 }
 ```
 
-### REST API
-
-- **Scope:** Enterprise Cloud (up to 90 days; Git events for 7 days)
-- **Monitors:** Same as GraphQL plus Git events (push, pull, merge)
-
-**Sample Request:**
-```http
-GET /orgs/{org}/audit-log?phrase=git.push
-Authorization: Bearer YOUR_TOKEN
-```
-
-
-## Investigating Missing Assets with Audit Log APIs
+## Investigating Missing Assets
 
 To recover or audit missing resources like repositories or teams:
 
-1. **Identify the asset** (e.g., `repository.deleted`).
-2. **Query the API** with event filters:
-   - **REST:** `?phrase=repository.deleted`
-   - **GraphQL:** `query auditLogEntries(query: "repository.deleted")`
-3. **Inspect metadata:** actor, timestamp, repository/team name.
-4. **Remediate:** restore from backup or revisit permissions.
+1. Identify the asset (e.g., `repository.deleted`).  
+2. Query the API with event filters:  
+   - **REST:** `?phrase=repository.deleted`  
+   - **GraphQL:** `query auditLogEntries(query: "repository.deleted")`  
+3. Inspect metadata: actor, timestamp, repository/team name.  
+4. Remediate: restore from backup or revisit permissions.  
 
 ```http
 GET /orgs/{org}/audit-log?phrase=repository.deleted
@@ -96,55 +93,68 @@ query {
 }
 ```
 
-
 ## Use Cases for Audit Logs
 
-- **Security incidents:** Trace unauthorized access or data exfiltration.
-- **Compliance audits:** Demonstrate policy enforcement (SOC 2, ISO 27001).
-- **Operational troubleshooting:** Diagnose CI/CD failures or permission errors.
-- **Access monitoring:** Review API token usage and SSH/Git activity.
-
-
-## Security & Compliance with Audit Logs
+- **Security incidents:** Trace unauthorized access or data exfiltration.  
+- **Compliance audits:** Demonstrate policy enforcement (SOC 2, ISO 27001).  
+- **Operational troubleshooting:** Diagnose CI/CD failures or permission errors.  
+- **Access monitoring:** Review API token usage and SSH/Git activity.  
 
-- **Data Retention:** 90 days on Enterprise Cloud; 120 days on Enterprise Server.
-- **Access Control:** Only owners and security managers view logs.
-- **IP Logging:** Records source IP to detect suspicious access.
-- **GDPR & Compliance:** Meets regional data-handling requirements.
+## Security & Compliance
 
+- **Data Retention:** 90 days on Enterprise Cloud; 120 days on Enterprise Server.  
+- **Access Control:** Only owners and security managers can view logs.  
+- **IP Logging:** Records source IP to detect suspicious access.  
+- **GDPR & Regional Compliance:** Meets data-handling requirements.  
 
 ## Audit Log Streaming
 
 Stream logs in real time to SIEM platforms (Splunk, Datadog) for long-term storage:
 
-1. Go to **Settings > Audit log**.
-2. Under **Streaming**, configure a destination (AWS S3, Azure Event Hubs).
-3. Verify events arrive in your SIEM.
-
+1. Go to **Settings > Audit log**.  
+2. Under **Streaming**, configure a destination (AWS S3, Azure Event Hubs).  
+3. Verify events arrive in your SIEM.  
 
 ## Additional Audit Log Types
 
-- **Git Activity Log:** Tracks pushes, pulls, merges (`phrase=git.push`).
-- **API Activity Log:** Tracks REST/GraphQL requests (`phrase=api.request`).
-- **Enterprise Managed Users (EMU):** Includes `user.login`, `repository.permissions_updated`, `repository.forked`.
-- **Token Usage:** Filter by `phrase=token` to identify compromised credentials.
-
-
-## Exporting Audit Logs via the Web UI
-
-1. In the upper-right corner, click your profile photo, then **Your organizations**.
-2. Next to your organization, click **Settings**.
-3. In **Archive** sidebar, select **Logs**, then click **Audit log**.
-
-
-Use the **Filters** field and **Export** menu to customize and download logs.
-
-
-## Exporting Audit Logs via API
+- **Git Activity Log:** Tracks pushes, pulls, merges (`phrase=git.push`).  
+- **API Activity Log:** Tracks REST/GraphQL requests (`phrase=api.request`).  
+- **Enterprise Managed Users (EMU):** Includes `user.login`, `repository.permissions_updated`, `repository.forked`.  
+- **Token Usage:** Filter by `phrase=token` to identify compromised credentials.  
+
+## Key Security Features of a GitHub Repository
+
+- **SECURITY.md:** Define reporting process and supported versions.  
+- **Branch Protection:** Enforce reviews, status checks, and commit signing.  
+- **Dependabot Alerts:** Automatic vulnerability detection and updates.  
+- **Code Scanning:** Continuous analysis via CodeQL.  
+- **Secret Scanning & Push Protection:** Real-time prevention and alerts.  
+- **Security Advisories:** Draft, collaborate, and publish advisories.  
+- **Dependency Graph:** Visualize and audit dependencies.  
+- **2FA & RBAC:** Enforce strong authentication and least privilege.  
+
+## API Access and Integrations
+
+| **Token Type**            | **Description**                                                       |
+| ------------------------- | --------------------------------------------------------------------- |
+| **Personal Access Tokens (PATs)** | Tied to a user account; simple scripts; broad scope. |
+| **Installation Tokens**    | For GitHub Apps installations; fine-grained permissions.            |
+| **OAuth Tokens**           | For OAuth apps; scoped access; requires least privilege.            |
+| **Device Tokens**          | For device-based authentication flows.                               |
+| **Refresh Tokens**         | To renew expired tokens without re-authentication.                   |
+
+| **Rate Limit Type**        | **Limit**                       |
+| -------------------------- | ------------------------------- |
+| **Unauthenticated**        | 60 requests per hour.           |
+| **Authenticated**          | 5,000 requests per hour.        |
+| **Apps**                   | Varies by installation.         |
+
+Check via API:
+```sh
+curl -H "Authorization: token YOUR_TOKEN" \
+     -H "Accept: application/vnd.github.v3+json" \
+     https://api.github.com/rate_limit
+```
 
-To ensure administrators to programmatically retrieve audit log data for analysis, compliance, or monitoring purposes, GitHub provides an API endpoint for exporting audit logs. Below is the REST endpoint used for fetching audit logs:
+GitHub Apps offer fine-grained permissions ideal for organizational integrations, while PATs suit basic scripts. OAuth Apps should be granted least privilege, with event subscriptions managed and reviewed regularly. Organizations can restrict untrusted apps through settings to enhance security. Enterprise Managed Users provide managed accounts with limited scope, ensuring compliance. Data residency policies help organizations store logs in specified regions, aligning with regulatory requirements.
 
-```http
-GET /orgs/{org}/audit-log
-Authorization: Bearer YOUR-TOKEN
-```