The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
package cmd
import (
"encoding/json"
"fmt"
"strings"
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/detect"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/threatrules"
)
var scanOpts struct {
userMode bool
systemMode bool
logPath string
rulesDir string
jsonOutput bool
minSeverity string
session string
failOn string
}
var scanCmd = &cobra.Command{
Use: "scan",
Short: "Run threat-detection rules over local agent telemetry",
Long: `Scans the local Beacon runtime telemetry log with the active threat-detection
rules and reports findings.
Rules come from the local store (~/.beacon/endpoint/rules) plus every built-in baseline
rule the store does not replace by id. Use --rules to scan with only an explicit rule
directory, and
'beacon rules add' / 'beacon rules pull' to manage the store.
Scanning is read-only and never touches the network.`,
SilenceUsage: true,
RunE: runScan,
}
// severityRanks maps --min-severity / --fail-on flag values to comparable ranks,
// delegating to the shared ordering in the threatrules package.
func severityRankOf(s asymptoteobserve.Severity) (int, bool) {
switch s {
case asymptoteobserve.SeverityInfo, asymptoteobserve.SeverityLow, asymptoteobserve.SeverityMedium,
asymptoteobserve.SeverityHigh, asymptoteobserve.SeverityCritical:
return threatrules.SeverityRank(s), true
}
return 0, false
}
func runScan(cmd *cobra.Command, args []string) error {
userMode := scanOpts.userMode
if scanOpts.systemMode {
userMode = false
}
var minRank int
if s := strings.TrimSpace(scanOpts.minSeverity); s != "" {
r, ok := severityRankOf(asymptoteobserve.Severity(s))
if !ok {
return fmt.Errorf("invalid --min-severity %q (info|low|medium|high|critical)", s)
}
minRank = r
}
failRank := -1
if s := strings.TrimSpace(scanOpts.failOn); s != "" {
r, ok := severityRankOf(asymptoteobserve.Severity(s))
if !ok {
return fmt.Errorf("invalid --fail-on %q (info|low|medium|high|critical)", s)
}
failRank = r
}
// Load and compile the active rule set.
loaded, skipped, err := detect.LoadActiveSkipping(userMode, strings.TrimSpace(scanOpts.rulesDir))
if err != nil {
return fmt.Errorf("load rules: %w", err)
}
if len(loaded) == 0 {
// The error names any skipped rules itself, so they are not also warned about.
return &detect.NoRulesError{Skipped: skipped}
}
detect.WarnSkipped(cmd.ErrOrStderr(), skipped)
compiled := make([]*threatrules.CompiledRule, 0, len(loaded))
for _, lr := range loaded {
c, err := threatrules.Compile(lr.Rule)
if err != nil {
return fmt.Errorf("compile rule %q: %w", lr.Rule.ID, err)
}
compiled = append(compiled, c)
}
// Stream the runtime log into memory (correlation needs the full ordered stream).
runtimeLog := lifecycle.ResolveRuntimeLog(userMode, scanOpts.logPath)
sessionFilter := strings.TrimSpace(scanOpts.session)
var events []asymptoteobserve.Event
err = dashboard.StreamEvents(runtimeLog.EffectiveLogPath, func(e schema.Event) error {
if sessionFilter != "" && (e.Session == nil || !scanSessionMatches(e.Session.ID, sessionFilter)) {
return nil
}
events = append(events, e)
return nil
})
if err != nil {
return fmt.Errorf("read telemetry %s: %w", runtimeLog.EffectiveLogPath, err)
}
// The rules engine evaluates the sequence it is handed, and the log is in append
// order, which is not the order the events happened: a hook writes the instant it
// intercepts a tool call while the exporter writes on its export interval. Ordered
// correlation rules silently miss without this.
threatrules.SortEvents(events)
findings, err := threatrules.ScanEvents(compiled, events)
if err != nil {
return fmt.Errorf("scan: %w", err)
}
// The --fail-on gate is a CI signal that must reflect every detection in the
// scan, so count it before --min-severity (a display-only filter) drops
// findings from the output slice.
failCount := 0
if failRank >= 0 {
failCount = threatrules.CountAtOrAbove(findings, failRank)
}
if minRank > 0 {
findings = threatrules.FilterBySeverity(findings, minRank)
}
// Highest severity first, then rule id, for stable, useful ordering.
threatrules.SortFindings(findings)
out := cmd.OutOrStdout()
if scanOpts.jsonOutput {
enc := json.NewEncoder(out)
enc.SetIndent("", " ")
if findings == nil {
findings = []threatrules.Finding{}
}
if err := enc.Encode(findings); err != nil {
return err
}
} else {
printFindings(cmd, findings, len(events), runtimeLog.EffectiveLogPath)
}
if failRank >= 0 && failCount > 0 {
return fmt.Errorf("scan found %d finding(s) at or above %q", failCount, scanOpts.failOn)
}
return nil
}
func scanSessionMatches(sessionID, query string) bool {
return strings.Contains(strings.ToLower(sessionID), strings.ToLower(strings.TrimSpace(query)))
}
func printFindings(cmd *cobra.Command, findings []threatrules.Finding, scanned int, logPath string) {
out := cmd.OutOrStdout()
if len(findings) == 0 {
fmt.Fprintf(out, "No findings (%d events scanned from %s).\n", scanned, logPath)
return
}
for _, f := range findings {
session := f.SessionID
if session == "" {
session = "-"
}
fmt.Fprintf(out, "[%s] %s session=%s\n", strings.ToUpper(string(f.Severity)), f.RuleID, session)
fmt.Fprintf(out, " %s\n", f.Reason)
for _, e := range f.Events {
fmt.Fprintf(out, " - %s %s\n", eventWhen(e), summarizeEvent(e))
}
}
fmt.Fprintf(out, "\n%d finding(s) across %d events.\n", len(findings), scanned)
}
func eventWhen(e asymptoteobserve.Event) string {
if e.Timestamp == "" {
return "(no ts)"
}
return e.Timestamp
}
// summarizeEvent renders a short, human one-liner of the matched event's salient field.
func summarizeEvent(e asymptoteobserve.Event) string {
switch {
case e.Command != nil && e.Command.Command != "":
return fmt.Sprintf("%s: %s", e.Event.Action, truncate(e.Command.Command, 100))
case e.File != nil && e.File.Path != "":
return fmt.Sprintf("%s: %s", e.Event.Action, e.File.Path)
case e.Prompt != nil && e.Prompt.Text != "":
return fmt.Sprintf("%s: %s", e.Event.Action, truncate(e.Prompt.Text, 100))
default:
return e.Event.Action
}
}
func truncate(s string, n int) string {
return truncateRunes(strings.NewReplacer("\n", " ", "\r", " ").Replace(s), n)
}
func init() {
scanCmd.Flags().BoolVar(&scanOpts.userMode, "user", true, "Use per-user endpoint paths")
scanCmd.Flags().BoolVar(&scanOpts.systemMode, "system", false, "Use system endpoint paths")
scanCmd.Flags().StringVar(&scanOpts.logPath, "log-path", "", "Runtime JSONL log path (default: resolved from config)")
scanCmd.Flags().StringVar(&scanOpts.rulesDir, "rules", "", "Rule directory to scan with, instead of the store and baseline")
scanCmd.Flags().BoolVar(&scanOpts.jsonOutput, "json", false, "Output findings as JSON")
scanCmd.Flags().StringVar(&scanOpts.minSeverity, "min-severity", "", "Only report findings at or above this severity")
scanCmd.Flags().StringVar(&scanOpts.session, "session", "", "Only scan events for this session id")
scanCmd.Flags().StringVar(&scanOpts.failOn, "fail-on", "", "Exit non-zero if any finding is at or above this severity")
rootCmd.AddCommand(scanCmd)
}