Pilot Audit Log

Comprehensive audit trail of all Pilot Protocol activity for security and compliance. Use this skill when: 1. You need detailed logs of all trust decisions a...

Security Scan

The skill's purpose (audit logging) matches its instructions, but the SKILL.md references undeclared environment variables and contains sloppy/unescaped shell usage that could lead to confusion or data exposure; review before use.

Purpose & Capability

Name and description align with the requested artifacts: it requires pilotctl and creates an audit directory under ~/.pilot/audit, which is appropriate for an audit-log skill. However the SKILL.md assumes an AGENT variable is available (used in pilotctl calls) but the skill metadata does not declare or require any environment variables—this is inconsistent.

Instruction Scope

Instructions instruct creating and appending to files under ~/.pilot/audit and running pilotctl (expected). They reference $AGENT and other shell variables without declaring or validating them. Several log commands concatenate raw variable contents into JSON/plain-text without escaping, which can produce malformed logs or allow injection of unexpected content into the audit file. The instructions do not send data to external endpoints unrelated to pilotctl, but the undeclared env var and unescaped usage are scope/safety issues.

Install Mechanism

Instruction-only skill with no install spec or downloads; lowest install risk. It relies on the existing pilotctl binary and (optionally) jq, which is consistent with the documented dependencies.

Credentials

The skill declares no required credentials or env vars (reasonable for a local audit tool). However the runtime instructions use $AGENT (and $HOME implicitly) without declaring them. The lack of declared env vars makes it unclear what privileges/inputs are expected. Audit files are written to the user's home directory—this is proportionate but may contain sensitive data and should be permissioned and documented.

Persistence & Privilege

always:false and user-invocable:true (defaults) — normal. The skill writes files in the user's home directory but does not request system-wide changes or other skills' configs. No elevated persistence privileges requested.

What to consider before installing

This skill appears to be an audit logger for Pilot Protocol and is generally coherent, but do the following before installing or running it: - Confirm what value should populate $AGENT (the SKILL.md uses $AGENT but no env var is declared); add a declared env var or replace with explicit agent IDs. - Review and sanitize inputs that go into the log (escape JSON and shell metacharacters) to avoid malformed logs or injection via agent names/results. - Ensure the audit directory (~/.pilot/audit) has correct permissions and a retention/back-up plan—logs may contain sensitive info. - Verify pilotctl's behavior for the handshake commands used here (they may perform network or trust changes) and ensure you trust the pilotctl binary and daemon being used. - Consider adding explicit instructions for log rotation, redaction of secrets, and validation of inputs in the SKILL.md. If you want me to, I can produce a safer, corrected SKILL.md snippet that declares expected env vars, escapes JSON properly, and documents permissions/retention recommendations.

Comprehensive audit logging for Pilot Protocol with structured event capture, retention policies, and compliance-ready output formats.

Commands

Initialize audit log:

mkdir -p ~/.pilot/audit
cat > ~/.pilot/audit/config.json <<EOF
{
  "enabled": true,
  "log_file": "$HOME/.pilot/audit/events.jsonl",
  "retention_days": 90,
  "event_types": ["trust.handshake", "trust.approve", "connection.open"]
}
EOF

Log trust events:

log_audit() {
  local EVENT_TYPE=$1
  local DETAILS=$2
  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $EVENT_TYPE $DETAILS" >> ~/.pilot/audit/events.jsonl
}

pilotctl --json handshake "$AGENT" "Audit test"
log_audit "trust.handshake" "{\"agent\": \"$AGENT\"}"

Query audit log:

grep "trust.approve" ~/.pilot/audit/events.jsonl
jq 'select(.event_type == "trust.approve")' ~/.pilot/audit/events.jsonl

Generate audit report:

cat > ~/.pilot/audit/report-$(date +%Y-%m-%d).json <<EOF
{
  "date": "$(date +%Y-%m-%d)",
  "total_events": $(wc -l < ~/.pilot/audit/events.jsonl),
  "handshakes": $(grep -c "trust.handshake" ~/.pilot/audit/events.jsonl || echo 0),
  "approvals": $(grep -c "trust.approve" ~/.pilot/audit/events.jsonl || echo 0)
}
EOF

Workflow Example

#!/bin/bash
# Audit logging with automatic event capture

AUDIT_DIR=~/.pilot/audit
LOG_FILE=$AUDIT_DIR/events.jsonl
mkdir -p "$AUDIT_DIR"

audit_log() {
  local EVENT_TYPE=$1
  local AGENT=$2
  local ACTION=$3
  local RESULT=$4

  cat >> "$LOG_FILE" <<EOF
{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","event_type":"$EVENT_TYPE","agent":"$AGENT","action":"$ACTION","result":"$RESULT"}
EOF
}

# Wrap trust commands with audit logging
audit_handshake() {
  local AGENT=$1
  audit_log "trust" "$AGENT" "handshake" "started"

  if pilotctl --json handshake "$AGENT" "Audit tracked"; then
    audit_log "trust" "$AGENT" "handshake" "success"
  else
    audit_log "trust" "$AGENT" "handshake" "failed"
  fi
}

audit_handshake "agent1.pilot"

Dependencies

Requires pilot-protocol skill, pilotctl binary, running daemon, and jq for JSON parsing.