Agent identity and attribution tracking — persistent agent IDs across scan sessions

[JBAhire]

Summary

Assign persistent identities to discovered agents so their security posture can be tracked across scan sessions, enabling lifecycle visibility and trend analysis.

Motivation

Currently, each g0 scan is a point-in-time snapshot. There's no way to answer:

• "Is this agent's security posture improving or degrading?"
• "When was this agent first discovered?"
• "What changed in this agent since last scan?"
• "Which agents have never been scanned?"

Agent identity tracking enables posture management, lifecycle governance, and fleet-wide visibility.

Proposed Implementation

1. Agent Fingerprinting

• Generate a stable agent ID from: file path, framework, agent name, tool set hash
• ID persists across scans even if minor details change
• Fuzzy matching for agents that move files or rename slightly

2. Agent Registry

• Local registry (SQLite or JSONL) at ~/.g0/agents.db
• Store per agent: ID, first-seen, last-seen, name, framework, file path, tool count
• Score history: array of (timestamp, score, grade, finding_count)
• Status: active, stale (not seen in N scans), removed

3. Lifecycle Events

• DISCOVERED — first time agent is seen
• UPDATED — agent configuration changed
• SCORE_CHANGED — security score changed (with delta)
• DEGRADED — score dropped below threshold
• IMPROVED — score improved above threshold
• STALE — not seen in configurable number of scans
• REMOVED — agent no longer exists in codebase

4. CLI Integration

• g0 scan output includes agent ID and trend indicator (↑↓→)
• g0 inventory --history — show agent lifecycle timeline
• g0 agents — list all tracked agents with last-seen and score trend
• g0 agents <id> — detailed agent history

5. Platform Integration

• Agent IDs synced to Guard0 Cloud via --upload
• Fleet-wide agent registry in platform dashboard
• Cross-machine agent correlation (same agent deployed to multiple endpoints)

Files to Create/Modify

• src/agents/fingerprint.ts — agent fingerprinting and ID generation
• src/agents/registry.ts — local agent registry with lifecycle tracking
• src/agents/lifecycle.ts — lifecycle event generation
• src/cli/commands/agents.ts — CLI command
• Update src/cli/ui.ts with trend indicators

Acceptance Criteria

• Stable agent IDs generated from agent properties
• Local registry tracks agents across scan sessions
• Lifecycle events generated and stored
• g0 agents command lists tracked agents
• Score trend indicators in scan output
• Agent IDs included in --upload data