From 044344755cdafb96a9e8a9fac54c298487ef1f8e Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Fri, 7 Mar 2025 03:32:45 +0000 Subject: [PATCH 1/2] Documentation updates from Promptless --- docs/reference/polykey-core/audit.md | 71 ++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/docs/reference/polykey-core/audit.md b/docs/reference/polykey-core/audit.md index cd078944..d69ec3e5 100644 --- a/docs/reference/polykey-core/audit.md +++ b/docs/reference/polykey-core/audit.md @@ -1 +1,72 @@ # Audit + +The Audit system in Polykey provides a way to track and retrieve events that occur within the Polykey agent. This feature is essential for security monitoring, troubleshooting, and compliance purposes. + +## Overview + +The Audit system records various events that occur during the operation of a Polykey node. These events are stored in a structured format and can be retrieved for analysis. The system is designed to be efficient and secure, with events stored in the node's database. + +## Core Components + +### Audit Class + +The `Audit` class is the main component of the audit system. It provides methods for: + +- Recording audit events +- Retrieving audit events +- Managing the audit event lifecycle + +### Audit Events + +Audit events have the following structure: + +- `id`: A unique identifier for the event +- `path`: An array of strings representing the event category/path +- `data`: The event data, which can contain any relevant information about the event + +## Usage + +### Retrieving Audit Events + +Audit events can be retrieved from a node using the `nodesAuditEventsGet` RPC method. This method supports: + +- Pagination through `seek` and `seekEnd` parameters +- Limiting the number of results with the `limit` parameter +- Ordering results in ascending or descending order + +Example usage through the node connection: + + + +### Event Types + +The audit system can record various types of events, including but not limited to: + +- Node connection events +- Authentication events +- Vault operations +- Secret access events +- Permission changes + +Each event type has a specific path structure and data format. + +## Security Considerations + +Audit events are stored locally on the node and are only accessible to authorized users with appropriate permissions. When retrieving audit events from another node, proper authentication and authorization are required. + +## Integration with Other Components + +The audit system is integrated with various components of the Polykey system: + +- The `PolykeyAgent` includes the audit system in its initialization +- The agent service exposes audit functionality through RPC methods +- Node connections can access audit events from connected nodes + +## Future Enhancements + +Future versions of the audit system may include: + +- Additional event types +- Enhanced filtering capabilities +- Export functionality for audit logs +- Integration with external logging systems \ No newline at end of file From b7ec36f8f6e6c9271e51ef7cf42e7208f948c055 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Sat, 8 Mar 2025 07:04:46 +0000 Subject: [PATCH 2/2] Update documentation based on feedback --- docs/reference/polykey-core/audit.md | 65 +++++++++++++++++++++++----- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/reference/polykey-core/audit.md b/docs/reference/polykey-core/audit.md index d69ec3e5..0d6c64d1 100644 --- a/docs/reference/polykey-core/audit.md +++ b/docs/reference/polykey-core/audit.md @@ -20,7 +20,7 @@ The `Audit` class is the main component of the audit system. It provides methods Audit events have the following structure: -- `id`: A unique identifier for the event +- `id`: A unique identifier for the event (AuditEventId) - `path`: An array of strings representing the event category/path - `data`: The event data, which can contain any relevant information about the event @@ -36,24 +36,41 @@ Audit events can be retrieved from a node using the `nodesAuditEventsGet` RPC me Example usage through the node connection: - +```typescript +// Retrieve audit events from a connected node +const response = await nodeConnection.getClient().methods.nodesAuditEventsGet({ + seek: 0, // Start from the beginning or specific audit event ID + seekEnd: Date.now(), // End at current time or specific audit event ID + limit: 100, // Limit the number of results + order: 'asc' // Order results (asc or desc) +}); + +// Process the audit events +for await (const auditEvent of response) { + console.log(`Event ID: ${auditEvent.id}`); + console.log(`Event Path: ${auditEvent.path.join('/')}`); + console.log(`Event Data:`, auditEvent.data); +} +``` ### Event Types The audit system can record various types of events, including but not limited to: -- Node connection events -- Authentication events -- Vault operations -- Secret access events -- Permission changes +- Node connection events (e.g., `['node', 'connection', 'forward']`) +- Authentication events (e.g., `['auth', 'success']`, `['auth', 'failure']`) +- Vault operations (e.g., `['vault', 'create']`, `['vault', 'delete']`) +- Secret access events (e.g., `['secret', 'read']`, `['secret', 'write']`) +- Permission changes (e.g., `['permission', 'grant']`, `['permission', 'revoke']`) -Each event type has a specific path structure and data format. +Each event type has a specific path structure and data format. The path is an array of strings that categorizes the event, while the data contains relevant information specific to that event type. ## Security Considerations Audit events are stored locally on the node and are only accessible to authorized users with appropriate permissions. When retrieving audit events from another node, proper authentication and authorization are required. +The audit system is designed to be secure and tamper-resistant, ensuring that audit events cannot be modified or deleted without proper authorization. + ## Integration with Other Components The audit system is integrated with various components of the Polykey system: @@ -62,11 +79,35 @@ The audit system is integrated with various components of the Polykey system: - The agent service exposes audit functionality through RPC methods - Node connections can access audit events from connected nodes +Example of how the audit system is integrated with the PolykeyAgent: + +```typescript +// In PolykeyAgent.ts +const agentService = agentServerManifest({ + audit: this.audit, + acl: this.acl, + db: this.db, + keyRing: this.keyRing, + // ... other components +}); +``` + +## Implementation Details + +The audit system is implemented using the following key files: + +- `src/audit/Audit.ts`: The main Audit class implementation +- `src/audit/types.ts`: Type definitions for audit events +- `src/audit/utils.ts`: Utility functions for audit operations +- `src/nodes/agent/handlers/NodesAuditEventsGet.ts`: Handler for retrieving audit events +- `src/nodes/agent/callers/nodesAuditEventsGet.ts`: Caller for the audit events RPC method + ## Future Enhancements Future versions of the audit system may include: -- Additional event types -- Enhanced filtering capabilities -- Export functionality for audit logs -- Integration with external logging systems \ No newline at end of file +- Additional event types for more comprehensive auditing +- Enhanced filtering capabilities based on event paths and data +- Export functionality for audit logs to common formats (CSV, JSON) +- Integration with external logging systems (Syslog, ELK stack) +- Real-time audit event notifications \ No newline at end of file