How to Use Audit Logs to Track Package Consumption and Policy Changes

Beginner 15 minutes Compliance Teams / Security Engineers Monitoring & Compliance

Navigate the audit page, filter events by actor/action/date, and build an audit trail for compliance reviews.

Overview

Chainsaw records every significant event as an audit log entry — package downloads, policy changes, credential management, configuration updates, and more. These logs provide the evidence trail needed for compliance audits, incident investigations, and understanding who did what and when.

Prerequisites

  • Manager role or above in Chainsaw
  • Activity flowing through the proxy (package installs, admin actions)

Step 1: Navigate to the Audit Page

Click Audit in the sidebar. The audit page shows a chronological feed of all events.

Audit log page
The audit page shows all events in chronological order

Step 2: Understand Event Types

Chainsaw records several categories of events:

CategoryExamples
Package ActivityPackage download, metadata request, blocked request
Policy ChangesPolicy created, updated, deleted, enabled/disabled
Credential ManagementClient created, secret reset, credential disabled
User ManagementUser invited, role changed, password reset
ConfigurationSettings changed, repository enabled/disabled
ExceptionsException created, expired, removed

Each event record includes:

FieldDescription
TimestampWhen the event occurred
ActorWho performed the action (user email or client ID)
ActionWhat was done
ResourceWhat was affected
DetailsAdditional context (policy conditions, package version, etc.)
OutcomeSuccess, failure, blocked
Audit event detail view
Each audit event includes full context about who, what, when, and why

Step 3: Filter Events

Use the filter controls to narrow down the audit log:

By Actor

Find all actions by a specific user or client:

Filtering audit logs by actor
Filter to see all actions by a specific user or client

By Action Type

Focus on specific event types (e.g., only policy changes):

Filtering audit logs by action type
Filter to see only policy changes or credential management events

By Date Range

Set a specific time window for your audit review:

Filtering audit logs by date range
Set a date range for compliance audit periods

Step 4: Build a Compliance Report

For periodic compliance reviews, combine audit logs with BOM exports:

  1. Set the date range to your compliance period (e.g., Q1 2026)
  2. Filter by action type to isolate the events you need:
    • Package downloads for consumption tracking
    • Policy changes for change management evidence
    • Exception activity for risk acceptance documentation
  3. Export the data for your compliance documentation
Pair audit logs with SBOM exports for a complete compliance package. The SBOM shows what’s in your supply chain, and the audit logs show how it got there.

Step 5: Investigate Incidents

When investigating a security incident, use audit logs to trace the timeline:

  1. Identify the package — Use the BOM to find the affected package
  2. Search audit logs — Filter by the package name to see when it was first installed
  3. Trace the client — Identify which credential downloaded the package
  4. Check policy history — See if any policies were changed that allowed the package through
Incident investigation timeline from audit logs
Reconstruct an incident timeline from audit log events

Step 6: Ingest Custom Audit Events

Chainsaw accepts custom audit events via the API for integration with external systems:

curl -X POST "https://chain305.com/chainproxy/api/v1/audit/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "external_scan_complete",
    "actor": "security-scanner",
    "resource": "npm/lodash@4.17.21",
    "details": "Third-party scan completed, no issues found",
    "outcome": "success"
  }'

This allows you to correlate Chainsaw events with external security tool results.

Integrate audit event ingestion with your SIEM or log aggregation system for centralized security monitoring.

Step 7: Use Billy for Audit Analysis

Ask Billy to help analyze audit patterns:

"What policy changes were made in the last 7 days?"

"Which user has created the most exceptions this month?"

"Show me all blocked events for the npm repository yesterday"
Billy analyzing audit logs
Billy can query the events table to answer audit questions

Next Steps