agentleFS
GTStaggGTStagg/project-eyas/CLAUDE.md

project-eyas

CLAUDE.md2 starsChanged yesterdayMITView on GitHub

Guidance for Claude Code in this repo. Surface-level facts: README.md, QUICKSTART.md, docs/DEPLOYMENT.md, docs/STANDALONE.md. Tenant-provisioning: docs/IR-SETUP.md, docs/SHADOW-AI-SETUP.md. Release history: CHANGELOG.md. Security posture: SECURITY.md. This file is the load-bearing stuff not visible from the code; deep gotchas live in the auto-memory index (MEMORY.md), referenced inline below. The current line is 0.11.x (0.11.0: the Python sidecar is gone — every Eyas tool runs in-process over eyas-mcp; 0.10.0 moved most of it onto eyas-mcp and set Claude 5.5 defaults) — see CHANGELOG.md. 0.3.0 was…

  • Reads credentials

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Tenant-relevant, not global catalogs: No flat global lists (50 random actors, full IOC feed) — filter to items with tenant evidence or make …

    line 23
  2. Distinctive:

    No redundant custom coverage: Don't propose custom IOC / IOA when Falcon Intel / cloud reputation already covers the behavior.

    line 24
  3. Distinctive:

    Dynamic-group restoration self-heals: Don't try to re-add after removing from quarantine.

    line 56

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Guidance for Claude Code in this repo. Surface-level facts: README.md, QUICKSTART.md, docs/DEPLOYMENT.md, docs/STANDALONE.md. Tenant-provisioning: docs/IR-SETUP.md, docs/SHADOW-AI-SETUP.md. Release history: CHANGELOG.md. Security posture: SECURITY.md. This file is the load-bearing stuff not visible from the code; deep gotchas live in the auto-memory index (MEMORY.md), referenced inline below.

The current line is 0.11.x (0.11.0: the Python sidecar is gone — every Eyas tool runs in-process over eyas-mcp; 0.10.0 moved most of it onto eyas-mcp and set Claude 5.5 defaults) — see CHANGELOG.md. 0.3.0 was the fresh-baseline cut: fresh-install-only, no migration path from older 0.20.x installs.

Project shape

Self-hosted Next.js console driving CrowdStrike Falcon through eyas-mcp, an independent MCP server derived from CrowdStrike's MIT-licensed falcon-mcp (attribution in NOTICE.md). Agentic operator console for Falcon-licensed teams, human-in-the-loop by design — not a Falcon-console replacement and explicitly not a tier-1 SOC autonomy product. Quality = depth of agentic workflows + reliability of approval-gated writes + durability of captured gotchas, not Falcon-console feature parity. New features strengthen the operator-console story; drift toward unattended multi-tenant triage is out of scope. See [project_positioning_2026_05].

The defining choice is an in-process MCP client (@modelcontextprotocol/sdk) inside Next.js paired with a manual Anthropic tool-use loop. We rejected Anthropic's native MCP connector to keep Falcon credentials and API calls on the host (tool results still reach the model — see SECURITY.md "Where data goes"), network exposure (eyas-mcp stays on a private bridge), per-tool approval gating, and ownable audit logging. In HTTP mode eyas-mcp uses x-api-key; the in-process client sets it via requestInit.headers on StreamableHTTPClientTransport.

eyas-mcp is the only MCP server (global rule: never depend on CrowdStrike's falcon-mcp, PyPI or otherwise). It's pinned by commit in versions.json (mcp-server-ref; mcp-server is the version label — currently 0.22.0 at bbe0e86), installed from git (uvx --from git+…@<ref> in dev, wheels built from source in bundles), never from a package index. A hosted-gateway build is planned (docs/HOSTED-MCP-ASSESSMENT.md). Capability split: generic Falcon operations belong in eyas-mcp (request missing ones there); Eyas-specific content — patch/cleanup script library, IR / Shadow-AI playbooks, classifier vocabularies, provisioning — stays in Eyas, layered over native tools (see memory project-eyas-mcp-capability-split). eyas-mcp exposes ~225 tools; ~210 reach the agent. The falcon-extras/ Python sidecar (FalconPy, stdio) is removed — every Eyas tool lives in lib/eyas-tools/, served in-process by the bridge under its extras_* name, and reaches Falcon only through eyas-mcp natives. Eyas runs exactly one MCP server. A few natives stay hidden in tool-bridge.ts — NATIVE_READ_KEEP (process tree: Eyas's tools walk it, then run Eyas's classifier), NATIVE_WRITE_SUPPRESS (writes whose Eyas twin adds a pre-write check, plus writes held back by decision: exclusion update, policy precedence, the Falcon Complete Message Center writes), PENDING_NATIVE_MIGRATION (bridge-only natives Eyas dispatches through).

Dispatch pattern (lib/mcp/native-dispatch.ts): an in-process Eyas tool whose Falcon write belongs to eyas-mcp validates/renders, builds a dispatch envelope and calls runDispatch, which carries it out on eyas-mcp natives and returns the old result shape. Today: patch/cleanup runs (falcon_create_rtr_script → falcon_run_rtr_script_on_hosts → falcon_delete_rtr_scripts), patch status, and the on-request bulk close (falcon_close_host_detections). Agent-facing tool names, approval gates and result shapes stay Eyas's.

Conventions

  • Strict separation between app/ (HTTP/UI) and lib/ (MCP client, Anthropic client, helpers). Importing lib/llm/ or lib/mcp/ from a client component is a bug.
  • Falcon and Anthropic credentials are server-only. No NEXT_PUBLIC_*, no client-side fetches to Anthropic or eyas-mcp.
  • Tool-call traces are first-class UI — the demo's main learning value.
  • Decision documents > ranked lists. Agentic surfaces produce 5–6 section verdicts (verdict / context / recommended actions), not smarter tables. In-page panels beat new pages for demo punch.
  • Tenant-relevant, not global catalogs. No flat global lists (50 random actors, full IOC feed) — filter to items with tenant evidence or make it agentic. The console is the catalog browser.
  • No redundant custom coverage. Don't propose custom IOC / IOA when Falcon Intel / cloud reputation already covers the behavior; escalate prevention policy instead. Chat system prompt enforces a falcon_search_indicators + falcon_search_iocs precheck before any falcon_add_ioc.
  • Deterministic enrichment + agentic synthesis. New cross-module surfaces follow this pattern: deterministic clustering / matching / correlation runs server-side in the route (pure functions, milliseconds), result attaches to existing data shapes (e.g. identity_overlap on QueueRow, campaigns on the queue payload, matches on intel hunt). The agent is invoked only on operator request via primer hand-off — never instructed to call a new tool from a long prompt. Agents bias hard toward known upstream falcon_* tools and routinely ignore even "REQUIRED" instructions for new extras_* tools — see feedback_deterministic_over_agent_instruction.
  • Standalone is a separate deployment surface from dev. Different env files, network constraints, auth paths — patches to one shouldn't be assumed to apply to the other. End-user guide is docs/STANDALONE.md.
  • No developer hints in user-facing copy. Operator-facing copy (headers, hints, labels, toasts, probe strings) never names file paths, frameworks/libraries (FalconPy, MCP, OAuth2), or jargon ("sidecar", "stdio"). Industry-standard CrowdStrike terms (MSSP, Flight Control, Member CID) ARE fine (they appear in Falcon Console). See feedback_user_facing_copy. Sanctioned exception: /agent-toolbox is an explicitly-labeled developer Reference surface — it intentionally shows raw tool names, provider names, and JSON schemas; a copy audit must NOT "plain-language" it, the rawness is the point. See [[agent_toolbox_surface]]. /blueprint is NOT exempt: its page copy is operator-facing (the advisor's streamed answers may still name tools).
  • Landing-page subtitles are one declarative sentence; no agent-internals telemetry. Banned phrases: "decision document", "5-section", "the agent fans out across…", "synthesize / synthesizes", "agent enumerates", "renders a posture decision document". Banned footnote: "Typical run: N-M iterations, X-Y seconds". System prompts to Claude in app/api/*/route.ts MAY use "decision document" — that's instructing model output format, not user-visible copy.
  • Primers carry load-bearing context, not boilerplate. Operator action buttons hand chat a ?primer=... URL to seed a turn. Primers are ONE declarative sentence + the data the agent can't get from the system prompt (composite ids, AIDs, hashes, posture verdicts, sample fires). The chat system prompt (app/api/chat/route.ts) owns decision-doc structure, tool-call ordering / dry-run mechanics, verdict-tagging (falcon_update_detections with add_tags=['true_positive'|'false_positive']), and approval-gate behavior — inlining any of that in a primer creates two drift surfaces. Gold-standard shape: Run the agentic IR workflow on host `X` (AID `Y`). Load the playbook with extras_ir_workflow_playbook and proceed. (feedback_primer_load_bearing_only). Operator-facing hand-off copy is NOT the primer string — components/primer.ts::describePrimer humanizes an instruction into a confirmation card (PendingActionCard) + summary bubble; the raw instruction is preserved behind a disclosure. Add a matcher + scripts/test-primer.mjs case per hand-off; no tool names/jargon in title/description (primer_handoff_humanizer). Every launch site routes through components/primerHandoff.ts::buildPrimerHref, never a bare /?primer=${encodeURIComponent(x)} — primers >~1500 chars overflow the request line and the seeded turn 431s; buildPrimerHref stashes long ones in sessionStorage and passes a short key.
  • Chat surface = terminal aesthetic, not a feature dashboard. components/Chat.tsx::EmptyState is intentionally bare: a $ agent --ready mono cap, one declarative paragraph, three ›-prefixed starter lines. Placeholder Eyas…. No marketing card, no module pills, no /queue CTA panel, no playbooks button — don't add one without explicit ask. Activity bar + tool-call bubbles + approval gates are the running-conversation surface. ConversationList is a pop-out drawer at every breakpoint (toggle at the chat column's top-left, not a rail), grouped Today / Yesterday / Earlier, with a filter box past 6.

Load-bearing gotchas

Short gotchas are inline; deep clusters live in linked memory files — read those before editing the surface. A backtick slug with no memory file is a forward-marker (many lost in the Linux→macOS move): the inline sentence is the record; promote it when you next work that surface.

Eyas tools / Falcon API / upstream

  • Native response handling in Eyas tools — read native results through ctx.callNative ({obj, error}) / ctx.searchNative ({ok, items, total} | scope_pending | error); never treat a missing resources as an empty success — a permission error is scope_pending (staged-build pattern: scope_pending_pattern) and an upstream 400 is an error, not count: 0.
  • Falcon API quirks (from the FalconPy era, still true underneath eyas-mcp): combined-endpoint sort uses dot, not pipe (falconpy_combined_endpoint_sort). IOA exclusions reject sort= entirely (falconpy_ioa_exclusions_no_sort). NGSIEM management endpoints need explicit repository / search_domain (ngsiem_management_endpoint_params). RTR class split (falconpy_rtr_method_naming). Threat Graph split by artifact type (threatgraph_hash_only). Custom IOC prevent is hash-only — for domain/ipv4/ipv6 use detect. v3 Alerts status is lifecycle-only; TP/FP is a tag (v3_alerts_status_vs_verdict). Prevention Policy + Custom IOA quirks (falcon_prevention_policy_quirks, falcon_custom_ioa_quirks, falconpy_prevention_policy_quirks). NGSIEM start_search needs APIHarnessV2 uber class (falconpy_ngsiem_uber_only).
  • MCP server quirks — dashboards keep a client-side re-sort (intra-page sort order was unstable ≤0.13.0). Search totals: native searches return {results, pagination: {total, …}}; projections.ts::searchTotalsHeader puts a [Search totals: …] line FIRST in every projected or capped search result, because the bridge unwraps envelopes to rows and the 12 KB cap cuts the JSON tail where pagination sits — without it the agent can't answer "how many" (test:projections). Falcon API 500s arrive as isError: false text — tool-bridge.ts::invoke runs parse.ts::detectFalconError on the agent path so a wrapped 500 becomes isError: true, not an empty success. falcon_search_vulnerabilities facet takes a list (["cve","host_info","remediation"]) — one call hydrates every block. Spotlight remediation shape (spotlight_remediation_shape). CISA KEV + exploit_status on Spotlight CVE (spotlight_cve_kev_signal). Spotlight 5000-row timeout (spotlight_5000_row_timeout). Per-host fan-out for fleet spread (vulnerabilities_per_host_fanout). Workflows execution-list timeout architecture (workflows_executions_timeout_architecture). Falcon Incidents/Cases filtered at bridge (falcon_incidents_filtered_at_bridge). falcon_remove_iocs Pydantic quirk (falcon_remove_iocs_pydantic_quirk). Spotlight FQL id:[...] rejected on row id (spotlight_row_id_filter_quirk).
  • NGSIEM CQL — head(N) not limit(N), double-quotes only, # tag prefix; field=/regex/ matches anywhere in the value unless anchored (verified live 2026-11-09; the older "full-match anchored" note was wrong). sort() defaults to limit=200 even with later head(N) (ngsiem_sort_default_limit_200). Every NGSIEM search goes through native falcon_search_ngsiem with check_cql=true, max_rows and a time_budget_seconds (eyas-mcp ≥ 7fd4031; it warns on unknown function names since 208acdd): /ngsiem (max_rows=100, time_budget_seconds=50), the remote-access-tool scan and the Shadow-AI hunts. A failed check comes back {ok: false, cql_lint, cql, fix}. The sidecar's own CQL linter and search runner are gone.
  • Approval-gate foot-gun — never pass requiresApproval: () => false to runAgentLoop on a write surface; that REPLACES the registry check entirely. See feedback_never_disable_approvals. Audited by /audit-write-tools.
  • Annotation approval backstop (v0.8.4) — the loop gates on requiresApproval(name) || bridge.annotatedNativeWrites.has(name); annotatedNativeWrites = visible native tools with readOnlyHint:false MINUS ANNOTATION_GATE_EXEMPT. Do NOT gate raw readOnlyHint:false — RTR session/read-only tools set it but are intentionally ungated (they're in the exempt set); gating them re-breaks live-host investigation UX. /agent-toolbox shows a drift banner (catalog.driftWarnings) if a native write is annotated-but-ungated. See annotation_approval_backstop.
  • IOA exclusion regex — Falcon's IOA DFA engine rejects zero-width assertions (^, $, \b, \A, \Z, \B). lib/eyas-tools/exclusions.ts runs a pre-flight check on every ifn_regex / cl_regex and fails locally with a useful error before round-tripping to Falcon. Canonical bounding pattern: r"...(\W.*)?" not r"...$". IR-readiness exclusion pattern is r".*\\powershell\.exe(\W.*)?". See ioa_exclusion_regex_pitfalls.

IR workflow + cleanup catalog

Full detail in ir_workflow_playbook. The invariants you can't violate without reading it:

  • Lives in chat, not an SSE route (/api/triage/host-ir deleted 2026-05-02; IR buttons hand off via primer). Scope capture is server-side (detectIrPrimer in app/api/chat/route.ts invokes the scope tools before the agent loop + hides them via IR_TOOL_FILTER) — never instruct the agent to call them.
  • Five phases, per-tool approval gated: Phase 0 Discovery → 1 Quarantine → 2 Remediation (dry-run → live) → 3 Verification → 4 Release/Hold. Phase 0 enrichment (cmdline_artifacts, registry_persistence) is mandatory-deterministic; Phase 4 closure is ledger-driven (extras_ir_close_remediated, closes only matched); contained_at_start vs agent_contained are sacred (Phase 4 only lifts what the agent applied). Per-engagement audit record in ir_runs / ir_run_turns.

Falcon Host Groups

  • Three group types, two static. static (by name) and staticByID accept add/remove identically; only dynamic rejects writes (falcon_host_group_static_by_id).
  • Host record groups field unreliable — use eyas-mcp's falcon_get_host_group_membership(device_id, verify="static") (≥ 7fd4031): it checks every static group one by one, 8 at a time within a 50 s budget. tool-bridge.ts::enforceToolArgs forces verify="static" (unless "all") whatever the agent passes. "all" can't finish within 60 s on large tenants; dynamic groups need no capture (they re-evaluate on their own). Loud-failure-on-error invariant: a per-group permission/upstream/transport error or a blown budget fails the whole call, never collapses to "not a member" — the list is authoritative for IR Phase 4 restore (a dropped group leaves a host un-restored). Kept OUT of LONG_RUNNING_TOOL_TIMEOUT_MS by design. See falcon_host_groups_field_unreliable.
  • Dynamic-group restoration self-heals. Don't try to re-add after removing from quarantine.
  • Create vs Adopt vs Clear. Each provisioning surface (IR Quarantine, Shadow-AI Banned) has THREE tools: extras_create_*_host_group(name) makes a fresh canonical-named group; extras_adopt_*_host_group(name) looks up an existing group by exact name (default = canonical, but ANY name works via override — agents commonly misread the docstring as canonical-only, see host_group_adopt_pattern); /config setup cards always render a paste/clear form so wrong ids can be fixed without DB surgery (setup_cards_always_show_apply). Auto-save via AUTO_SAVE_TOOLS in app/api/chat/route.ts — hook is generic on {ok:true, id} shape so extending it for a new write tool is one map entry.
  • Same-turn group reads must see a just-saved group. The chat route's auto-save hook writes a created/adopted group id to the DB mid-turn. Every group reader is in-process now (lib/eyas-tools/: the IR quarantine and Shadow-AI banned diagnose / create / adopt / provision, IR readiness, the binding check, the playbooks) and reads the config store at call time, so it sees the new id at once. No child process gets the group ids any more (spawn-env.ts strips them). The sidecar's old frozen-env workaround (resolve_group_id / set_runtime_group_id) is gone with it (sidecar_frozen_env_runtime_override is history).
  • Diagnose 404 = group_missing, not raw upstream error. Both extras_diagnose_quarantine_setup and extras_diagnose_shadow_ai_banned_setup reclassify HTTP 404 on the host-group lookup as case="group_missing" so /config shows the friendly Create/Adopt CTA instead of surfacing the cryptic upstream error (diagnose_404_as_group_missing).
  • Tenant teardown. extras_teardown_project_eyas_managed(dry_run=True) (lib/eyas-tools/teardown.ts) wipes every canonical Project Eyas object (host groups, prevention policies, IOA rule groups, IR-readiness exclusion) in Falcon-enforced dependency order. Single approval. The IR-readiness exclusion is matched by the RTR-preamble marker in cl_regex (or its canonical name) — the old comment-substring match never found it. Companion low-level deletes (extras_delete_prevention_policy with disable_first, extras_delete_ioa_rule_group). Known gaps: no scope filter (nukes IR+Shadow-AI together); doesn't touch non-Project Eyas IOA rule groups bound to canonical policies. See tenant_teardown_tool.

Agentic patching (RTR) + Falcon-published scripts

  • Inline runscript -Raw= broken for any body with single quotes — always CloudFile (rtr_runscript_cloudfile_only).
  • Patch / cleanup tools live in Eyas (lib/eyas-tools/rtr-tools.ts, library lib/eyas-tools/rtr/library.ts, manifests + scripts under lib/eyas-tools/rtr/{patching,cleanup}/, shipped via next.config.ts outputFileTracingIncludes). Eyas validates + renders; on dry_run=false extras_rtr_run_patch / _run_cleanup call runDispatch (lib/mcp/native-dispatch.ts) with the bridge-only natives — falcon_create_rtr_script (private one-off eyas-run-<hex>) → falcon_run_rtr_script_on_hosts → falcon_delete_rtr_scripts in finally — and return the old results[] shape (cloud_request_id = native task_id, exit_code null); extras_rtr_check_patch_status polls falcon_check_rtr_admin_command_status. The script natives stay hidden in PENDING_NATIVE_MIGRATION so the agent can never upload bytes.
  • Render-time security in lib/eyas-tools/rtr/library.ts — agent supplies validated id + params, never script bytes. validateParams enforces enum + regex per manifest schema (Python re patterns run as JS: fullmatch anchoring, leading (?i) → i flag, no other inline flags); asciiCoerce is the render-time backstop (RTR transport mangles non-ASCII under SYSTEM) and must keep ? — the Python version stripped every ?, breaking rc=$? and query-string URLs. test:rtr-library covers it.
  • Manifest ordering matters. First-declared-wins; win-wsl-update before win-update-install. Run /audit-remediations after any manifest change — per-script /verify-patch can't catch silent shadowing (feedback_audit_after_manifest_change).
  • Windows Update via WUA COM API, not PSWindowsUpdate (windows_update_wua_com_api). App installers via direct vendor MSI URLs, not winget. JRE exception: app-jre-uninstall walks registry for legacy Oracle/Sun JRE 6/7/8 only.
  • MCP 60s timeout caps batch_admin_command (mcp_timeout_vs_falcon_wait) — runs pass timeout_seconds=40 (eyas-mcp sets the per-host wait 5 s shorter) and the bridge gives that native call a 100 s client timeout, since session open + command can each wait; the agent polls via extras_rtr_check_patch_status. Tools that legitimately block longer than 60s (currently eyas-mcp's falcon_wait_for_rtr_sessions, the Phase 1.5 propagation wait; enforceToolArgs always sets probe="runscript" so readiness means a real probe script ran, not just a session opening — needs RTR Admin write, eyas-mcp ≥ 2703a99) get a per-call transport-timeout override via LONG_RUNNING_TOOL_TIMEOUT_MS in tool-bridge.ts; without it the SDK aborts the wait at ~60s and the agent skips to HOLD. Reserve this for tools that inherently block >60s; latency you can fix belongs in the impl, not an override (see falcon_host_groups_field_unreliable for the canonical fix).
  • Falcon-published RTR scripts: server SKU quirks (falcon_scripts_workstation_quirks). Token defense: projectFalconScriptRun caps result[] at 50 with _truncated. list_falcon_scripts(limit=200) silently returns zero — use default.

Sub-agent fan-out

  • lib/chat/sub-agent.ts::runSubAgent — focused, non-streaming child loop for parallel data-gathering inside a single route. See subagent_fanout_pattern.
  • Each subagent spawns its own MCP client by default (mcp_persistent_singleton). The native server handles concurrent requests on one connection (behavior eyas-mcp inherited from falcon-mcp 0.16.0, ~2.4× faster warm), so /investigate can share the native client behind EYAS_POOL_SUBAGENT_MCP=1 (default off). Eyas's own tools run in-process, so there's no second client. See [[falcon_mcp_v0_16_upgrade]].
  • Sub-agents are read-only at the toolset layer. runSubAgent rejects any name in REQUIRES_APPROVAL from the filter regardless of caller intent. /audit-write-tools greps for this.
  • Sub-agents collect, parent route forwards synthetic tool_use + tool_result events AFTER completion with namespaced ids.
  • Per-slice surface attribution (investigate:fingerprint etc.) in lib/cost/log.ts.

Shadow-AI

  • IOA needs installer rules, not just launch rules (shadow_ai_ioa_installer_rules).
  • extras_shadow_ai_check_prevention_binding diagnoses Ban+Clean enforcement chain (shadow_ai_prevention_binding_probe).
  • Sanctioning is per-tool, per-tenant, settings.json-resident (shadow_ai_sanctioning_per_tool).

/hosts page

  • Thin client shell — each section calls its own API on demand. /api/hosts/at-risk, /contained, /search, /groups/list, /groups/members.
  • Per-host action buttons: Investigate (read-only, no eligibility check, must mirror across DetectionsTable / QueueTable / VulnerabilitiesTable per feedback_pivot_consistency) and IR. IR eligibility is one shared predicate (lib/hosts/ir-eligibility.ts) rendered by components/irEligibility.tsx::IrChip — the chip is ALWAYS shown with three explicit states: eligible / ineligible-with-tooltip / off→links to /config. /queue uses the same predicate (the prior Linux-gets-IR queue bug is fixed). Lenient on sparse data; surfaces that aren't detection-triage pass showIr={false}. See ir_button_eligibility_unified.
  • No purple in UI — teal for Contained panel, blue for ngsiem lateral-movement (feedback_no_purple).

Light-mode theming

Variable-flip under [data-theme="light"] in app/globals.css, not a component sweep. New components: use bg-neutral-* over bg-black, text-white headlines over hex. Full inversion rules (neutral symmetric, --color-white flips but --color-black doesn't, chromatic asymmetric remap, brand/oxblood not flipped) in light_mode_variable_flip.

Other quirks

  • SSE cancellation via ReadableStream.cancel, not request.signal. lib/chat/stream-agent.ts creates AbortController, hands signal to ctx, aborts on cancel(). runAgentLoop checks signal at iteration start + after tool-results. Anthropic SDK gets signal as second positional arg. AbortError filtered in streamAgent + agent-loop + AgentRun/Chat catches. New SSE routes must thread signal through. awaitApproval is also signal-aware (lib/chat/approvals.ts): a disconnect/Stop during a pending write-approval resolves it immediately as timeout instead of blocking the full 5-min window — releasing the in-flight lock (env-switch would otherwise 409) + the idle MCP clients, and deleting the pending entry so a resume can't re-stamp a live Allow button on a dead loop.
  • MCP clients spawn fresh per call — don't pool them (mcp_persistent_singleton).
  • Prompt cache needs a byte-identical prefix (lib/llm/prompt-cache.ts). eyas-mcp lists tools, resources and schema examples / enum / required in a different order per Python process (and in dev it starts per turn), so buildToolBridge returns them sorted; without that every chat turn re-wrote the ~175K-token tools + system cache. The agent and sub-agent loops also put a moving cache marker on the conversation tail (withHistoryCacheMarker, same TTL as the system block) so tool results aren't re-sent uncached each iteration. Anything per-turn that goes into tools or the system prompt breaks the cache: put it after the cached system block (contextBlocks). Check with /cost-summary (cache hit %).
  • Health endpoints split. /api/healthz is the cheap public liveness probe (no upstream calls) — suitable for orchestrator + uptime monitors. /api/health is full diagnostics (Anthropic + Falcon MCP + extras probes) and is authenticated; ?force=1 triggers a fresh fanout behind the same auth gate. getHealthReport() cached for 30s with in-flight de-dup.
  • instrumentation.ts Node-only imports inside if (process.env.NEXT_RUNTIME === "nodejs") (instrumentation_runtime_guard).
  • Anthropic gateways 404 on /v1/models (gateway_models_endpoint) — lib/health.ts::probeAnthropic downgrades to ok-with-note when ANTHROPIC_AUTH_TOKEN is set.
  • Conversation history + resume (claude.ai-style) — chat_sessions table; 72h rolling idle TTL is the single source of truth in lib/chat/state.ts::TTL_MS (route emits session_state SSE with expiresAt). /chat mounts fresh — no auto-resume; resumable only via the ConversationList pop-out drawer. Pending approvals survive resume (listPendingForSession restamps). Full detail in chat_history_db_persistence.
  • Falcon Intel raw shape: nested {value} objects + epoch seconds; only flattened on agent path (falcon_intel_dashboard_shapes). Dashboards must normalize.
  • Synchronous in-flight guard in AgentRun — useRef<boolean> not busy state (state updates lag back-to-back calls).
  • Markdown overflow defenses — .markdown table is display: block; overflow-x: auto; use overflow-wrap: break-word NOT anywhere/word-break: break-word (splits 10.20.30.40).
  • Next.js unstable_cache 2MB limit (unstable_cache_2mb_limit) — vuln payloads bust it silently; use module-scoped Map.
  • HOSTNAME quirk on macOS standalone — zsh auto-exports; start.sh forces HOSTNAME=127.0.0.1.
  • Session cookie Secure keys off x-forwarded-proto, NOT NODE_ENV — both lib/auth/session.ts and middleware.ts derive secure from the request scheme. The standalone bundle runs NODE_ENV=production over plain HTTP, where a Secure cookie is silently dropped and rolling-renewal logs the operator out. A TLS-terminating proxy sets x-forwarded-proto=https so real HTTPS deploys still get Secure. Don't "fix" this back to NODE_ENV.
  • Agent-supplied FQL / GraphQL inputs are reject-validated, never escaped — eyas-mcp's identity tools check user names against a strict charset and AIDs as 32 hex before interpolating (the retired sidecar twin rejected ' / \). Apply the same reject-don't-escape pattern to any new agent-supplied string interpolated into an FQL literal.
  • Falcon FQL has no ~ or contains operator (fql_wildcard_operator) — wildcard/substring matching uses asterisks inside the quoted value: name:'*chrome*'. The agent has guessed name:~ and received a filter-syntax rejection. Any Eyas tool description with a filterable string field MUST show the asterisk form and note that ~ is invalid.
  • macOS first-launch native-binding walls (macos_first_launch_native_bindings) — start.sh strips com.apple.quarantine (Gatekeeper on unsigned .node) AND picks the matching better-sqlite3 prebuild from vendor/better-sqlite3-prebuilds/<target>-<abi>/ based on the recipient's process.versions.modules. make-dist.sh stages one prebuild per supported ABI (currently 127 Node 22, 137 Node 24) from upstream WiseLibs Releases. Adding a new Node LTS = append to BSQLITE_ABIS=(…); may require a better-sqlite3 major bump.
  • Standalone install — bundle ships install.sh (from scripts/gen-install.sh, quoted-template so $HOME resolves on the recipient, never the builder) → eyas launcher in ~/.local/bin (start/stop/restart/status/logs). No in-app update (removed 0.9.1): upgrading = running a newer bundle's install.sh (rsync preserves .env+data/). eyas does NOT use the shared macos-standalone generator (builder-$HOME + nohup _node bugs).
  • globalThis-pin process-wide module state in Next.js standalone (module_state_globalthis_pinning).
  • Standalone secret warmup must block (standalone_secret_warmup_blocking).
  • CrowdStrike AIDR — Pangea envelope (aidr_pangea_envelope) — guardChatCompletions returns {status, result: {blocked, detectors, ...}}; read at resp.result.* not resp.*. Detector keys: malicious_prompt, confidential_and_pii_entity, secret_and_key_entity, etc. — gate on detected: true (no action field).
  • DB WAL checkpoint on shutdown (db_wal_checkpoint_on_shutdown) — lib/db/client.ts registers SIGTERM/SIGINT/SIGHUP/beforeExit → wal_checkpoint(TRUNCATE) + close(). Without it, every kill leaves writes only in eyas.db-wal and the main file stays at ~12 KB. SQLite auto-checkpoint at 1000 pages is well above what this app accumulates.
  • tool-bridge.invoke returns content as a string (tool_bridge_content_is_string) — joined MCP blocks, NOT the raw Array<{type,text}>. onToolResult callbacks must accept both shapes; assuming the array form silently no-op's against the bridge.
  • Scope-denial detection via isScopeDenied (v0.8.4), NOT substring (falcon_mcp_error_scope_signaling) — eyas-mcp (as falcon-mcp did) returns errors as isError:false + {error,details:{status_code},required_scopes?}; the inherited 0.13.0-era 403 message is "Permission denied. The API credentials don't have the required access." (NOT the raw CS phrasings "scope not permitted"/"access denied"). lib/mcp/parse.ts::isScopeDenied keys on status_code/required_scopes/scope_pending (substring fallback); shared by health.ts probes + cases/quarantine/correlation/data-protection routes + snapshot. Keep the nav gate and the page on the same helper. Block-aware parseToolResultObjects(content) parses each MCP block directly (agent path only; dashboards keep parseConcatenatedJson).

Where things live

  • app/ — Next.js App Router pages + API routes. Agentic SSE routes own a system prompt + single agent loop each; dashboard fetchers have no LLM.
  • lib/llm/anthropic.ts — Anthropic SDK singleton (@anthropic-ai/sdk 1.3.0, API version 2026-10-21). SDK 1.x holds one credential per client and sends an API key as Bearer; anthropicClientOptions keeps Eyas's old wire headers (API key as X-Api-Key, token as Bearer, both when both are set) so gateways see no change — every new Anthropic(...) goes through it. Every Claude request goes through lib/llm/messages.ts::createMessage / streamMessage (beta Messages namespace) — never client.messages.* directly. They apply lib/llm/request.ts::withModelDefaults: max_tokens floor of 16K (thinking counts against it on the 5.5 generation — the old 1K–8K per-route caps truncate), explicit output_config.effort: "medium" only where the model accepts it (not Haiku 4.5 / Sonnet 4.5 / older), and server-side refusal fallbacks (fallbacks: "default", beta server-side-fallback-2026-07-01) on claude-opus-5-5 / claude-sonnet-5-5 only. A request with fallbacks that 400/404/422s before any output is retried once without them; if that works the base URL is remembered as not supporting them (reset on /config change), so a gateway that rejects the beta degrades instead of failing the turn. Echo assistant turns with assistantTurnContent and run tools from toolUsesToRun: fallback blocks stay in place unchanged; thinking / tool_use / unpaired server-tool blocks BEFORE the last fallback block are dropped (the API rejects them). Default model claude-sonnet-5-5 (lib/config/runtime.ts), claude-opus-5-5 the higher-quality option. Never send temperature / top_p / thinking: disabled / budget_tokens / forced tool_choice / assistant prefill — all 400 on the 5.5 models; keep messages append-only (thinking blocks are passed back unchanged; chat_sessions stores them verbatim). A stop_reason: "refusal" that survives the fallback chain (or a category with no fallback: bio, reasoning_extraction, general_harms) ends the turn with a plain notice and the declined turn is not kept (an empty assistant turn would 400 the next request). Pricing per version in lib/cost/pricing.ts.
  • lib/mcp/ — falcon-client.ts (withFalconMcpClient), tool-bridge.ts (merges the eyas-mcp tool list with Eyas's in-process tools; suppression sets NATIVE_WRITE_SUPPRESS / NATIVE_READ_KEEP / PENDING_NATIVE_MIGRATION, enforceToolArgs (forces verify="static" on group membership and probe="runscript" on falcon_wait_for_rtr_sessions), long-call timeouts in LONG_RUNNING_TOOL_TIMEOUT_MS, filters incident/crowd_score), parse.ts / projections.ts (token-bounding + cmdline_artifacts + registry_persistence + pivot_pid extraction), write-tools.ts (approval-gated registry), native-dispatch.ts (carries out Eyas tools' dispatch envelopes on eyas-mcp natives — RTR script runs, patch status, bulk close; pure, test:native-dispatch), native-shape.ts / native-payload.ts (shape native search envelopes into {ok, items, count, total, totals_by_entity_type?} for deterministic consumers), catalog.ts (the agent-visible tool catalog behind /agent-toolbox — reuses buildToolBridge so it can't drift from what the agent sees; globalThis-TTL-cached like lib/health.ts).
  • lib/prevention/posture.ts — prevention posture for /prevention, home, Shadow-AI setup and the snapshot from falcon_get_prevention_posture, with Eyas's detect-only rule (only OnSensorMLSlider / CloudAntiMalware count). projections.ts renders the native result one line per policy for the agent. lib/recon/preview.ts — reject-validated Recon preview args + corpus summary for the intel dossier.
  • lib/chat/ — agent-loop.ts (manual loop, pauses on write tools, per-tool duration_ms, optional toolFilter), sub-agent.ts (focused child loop, own MCP clients, write-shape filtered), approvals.ts (resolveApproval(toolUseId, decision, expectedSessionId) — pending entries are bound to the originating chat sessionId so a forged or stray request from another tab can't resolve them; ApprovalButtons reads sessionId from localStorage), state.ts (carries IrMode { aid, startedAt, recordPath, turnCount } per session), ir-run-record.ts (per-IR-session record backed by ir_runs + ir_run_turns tables; basename <aid>-<startedAt>.json is the URL slug and lookup key; recentIrCostProjection for kickoff projection). Decision is "allow" | "deny" | "timeout".
  • lib/scheduler/ — manifest-driven recurring-job runtime. Add: one file under lib/scheduler/jobs/ + one line in index.ts. Registered: patch-digest, daily-briefing, release-watcher (compares the versions.json eyas-mcp pin with GTStagg/eyas-mcp main via GitHub's compare API — eyas-mcp has no releases/tags; never watches crowdstrike/falcon-mcp).
  • lib/cost/ — Anthropic pricing table (longest-prefix match). Append-only inserts into the cost_log table in data/eyas.db. logUsage() fire-and-forget.
  • lib/db/ — SQLite (better-sqlite3) + Drizzle ORM (queries) + custom SQL migration runner. client.ts globalThis-pinned WAL handle. crypto.ts AES-256-GCM column encryption (HKDF from AUTH_SESSION_SECRET; rotating the secret intentionally invalidates encrypted creds — see [db-column-encryption-contract]). migrate.ts forward-only with checksum drift + downgrade trap + pre-migrate backup (see [db-migration-runner-safety]). bootstrap.ts awaited by instrumentation.ts per standalone_secret_warmup_blocking. Migrations live as numbered .sql files; never edit a shipped one — add 000N_<name>.sql for changes. 0.3.0 squashed prior migrations into a single 0001_init.sql baseline; fresh-install only.
  • lib/auth/ — store.ts (Node crypto.scrypt → single-row auth table in data/eyas.db) + session.ts (iron-session, 7-day rolling). Root middleware.ts gates everything except /login, /register, /api/auth/*, /api/healthz, static. /api/health is authed.
  • lib/config/ — store.ts is single owner of the settings + environments tables in data/eyas.db. Holds Anthropic creds and the multi-environment Falcon list (per-env IR quarantine group + Shadow-AI banned group + sanctioned tools + active_id). runtime.ts / environments.ts delegate. .env is not consulted at runtime — the DB is authoritative (config_single_source_of_truth). spawn-env.ts::childProcessEnv() set-or-strips every credential / per-tenant field on every spawn (spawn_env_per_tenant_strip). Every mutateSettings() runs in one atomic transaction across settings + environments + the SQL-trigger-enforced append-only settings_audit table. Active-env switch refused with 409 while lib/chat/in-flight.ts::isBusy() is true.
  • Secrets at rest: Falcon + Anthropic creds AES-256-GCM column-encrypted in data/eyas.db (mechanism in lib/db/ above); DB file mode 0600. The macOS-Keychain / node-keytar variant was rejected because target Macs block the native .node binary. See [db-column-encryption-contract].
  • Build-time deployment lock: lib/config/build-flags.ts exports BUILD_FLAGS = { gatewayOnly, forcedGatewayUrl }. Dev defaults false/null; make-dist.sh overwrites before npm run build to bake in the standalone gateway lock, restores after build. lib/config/deployment-policy.ts::validateAnthropicAgainstPolicy() enforces server-side. A leaked bundle copy must be unable to be repointed.
  • Threat model: mode 0600 on data/eyas.db + .env protects against other Unix users on the box. An exfiltrated DB alone is unreadable — the attacker also needs AUTH_SESSION_SECRET from .env (the HKDF root). Residual risks: backup hygiene (a synced folder capturing BOTH data/ and .env defeats the separation), no graceful re-key for AUTH_SESSION_SECRET rotation (rotation invalidates every encrypted credential by design), SDK debug logging lands tokens in stdout.
  • lib/eyas-tools/ — Eyas's own agent tools served in-process by tool-bridge.ts (they replaced the old sidecar tools of the same extras_* name). EyasTool = name + description + input schema + run(input, {callNative}); any Falcon call goes through eyas-mcp natives via callNative. Register in index.ts; classify in write-tools.ts (test:tool-classification enforces it). Today: the four workflow playbooks (playbooks/*.ts text; inputs reject-validated because playbook results reach the model unfenced) the RTR script library tools (rtr-tools.ts: list / resolve / run patch + cleanup, patch status, patch profiles, coverage), static host-group membership writes (host-group-tools.ts, over falcon_perform_host_group_action), IR quarantine group diagnose / create / adopt + IR readiness (quarantine.ts), tenant teardown + the policy / rule-group deletes (teardown.ts), the IR detection scope and closers (ir/: Phase 0 scope + actionable partition, Phase 3 verification + the release gate's prior re-check, the ledger close, the untouched-originals close and the bulk close; paged falcon_search_detections, closes via falcon_update_detections 500 ids at a time; the AI-egress list the IR classifiers and the Shadow-AI hunts share is ai-egress-catalog.json), and IR quarantine policy provisioning + policy detach (quarantine-provision.ts: adopt or create per platform, max-protective settings push, falcon_set_policy_precedence with move_id + place_first, readiness exclusion via falcon_create_exclusion with skip_if_duplicate), the Shadow-AI hunts (shadow-ai/hunt.ts over the catalog in shadow-ai/catalog.ts: the per-host four-layer scan runs its three NGSIEM searches in parallel, the fleet egress search is one; the sanction list is read from the active environment at call time; test:shadow-ai), IOA / ML exclusions (exclusions.ts: list, and creates that refuse a duplicate and, for IOA, reject zero-width regex assertions before falcon_create_exclusion), the Data Protection creates (data-protection.ts: monitor-first bodies over falcon_create_data_security_entity; test:exclusions covers both), Shadow-AI setup and prevention (shadow-ai/prevention.ts: banned group diagnose / create / adopt, policy provisioning placed after the IR quarantine policy via falcon_set_policy_precedence place_after, rule-group status, the binding check, and the adopt that authors the per-platform Custom IOA corpus in shadow-ai/ioa-corpus.json and converges rules with one batched falcon_update_ioa_rule; test:shadow-ai-prevention), and the process-tree family (ir/process-tree.ts, ir/campaign-scope.ts, ir/rat-scan.ts: the host process tree and the campaign scope walk the hidden native falcon_get_process_tree and run Eyas's delivery-vector classifier in process-tree/classifier.ts over its nodes; the remote-access-tool scan is one bounded falcon_search_ngsiem; test:process-tree). Tools that need rows from a native search use ctx.searchNative.
  • No Python in Eyas itself. The sidecar, its venv, its wheels, test:sidecar and its deploy verification (expected_tools.json, verify_tools.py, the /status add-on row) are gone; /validate-bundle fails a bundle that carries any falcon-extras/ file. The only Python is eyas-mcp, run by uvx (dev) or installed from the bundled wheels. test:tool-classification + /agent-toolbox (catalog drift warnings) are the in-process tool contract.
  • lib/queue/ — rank.ts (deterministic detection ranking + IdentityOverlap), campaigns.ts (cross-host clustering).
  • lib/intel/ — hunt.ts (intel-to-tenant matcher, three-tier verdict), attribution.ts (/intel page-level adversary graph), adversary.ts (per-row chip enrichment — extractAdversaryIds + enrichRowsWithAdversary batch-resolve via one falcon_search_actors call).
  • lib/discover/inventory.ts — deterministic posture enrichment for /discover (normalize + summarize + renderDiscoverContext): managed/unmanaged coverage gaps, privileged/local-admin accounts, suspicious apps. All three entities come from native eyas-mcp tools via lib/discover/native.ts::fetchDiscoverSnapshot (shared with the posture snapshot): assets from falcon_search_assets (eyas-mcp ≥ 7fd4031) as two calls merged by normalizeAssetSearch — every entity type with include_type_totals (tenant-wide managed / unmanaged / unsupported / other counts → breakdown, otherTypes), plus an entity_type:'unmanaged' sample for the coverage-gap list — applications from falcon_search_applications with NO filter (no match-all filter exists — name:'*' silently returns 0) and fields:"compact", accounts from falcon_search_accounts. Results are shaped by lib/mcp/native-shape.ts. Capability gate is FalconMcpCapabilities.discover. See [[falcon_scope_probe_and_discover]].
  • scripts/falcon-scope-probe.mjs — live per-environment API-posture probe; authoritative reconciliation for components/ScopeChecklist.tsx drift (node scripts/falcon-scope-probe.mjs --all). See [[falcon_scope_probe_and_discover]].

Project skills (.claude/skills/)

  • /patch-context — bootstrap reads + conventions for catalog work.
  • /verify-patch <id> — render + non-ASCII + spotlight smoke test.
  • /audit-remediations — live Spotlight extract + bucket diff against manifest. Run after any patching manifest change.
  • /verify-feature — invoke after implementing a change to confirm end-to-end before declaring done. UI → Playwright; auth bypassed via tests/auth.setup.ts sealing a session cookie using AUTH_SESSION_SECRET (playwright_auth_seal_pattern, playwright_env_self_load).
  • Release bump (no skill): one PR that sets the version in package.json, both top-level version fields of package-lock.json, the README lead line (**vX.Y.Z**), and renames CHANGELOG ## Unreleased to ## X.Y.Z — <one-line theme>. Run /audit-write-tools before it. Tags and GitHub releases are a separate, explicit step.
  • /validate-bundle — invoke after ./make-dist.sh. Structural checks + smoke-boot. Hard-required before shipping (feedback_validate_after_every_build).
  • /audit-write-tools — diffs write-shape Eyas tools against REQUIRES_APPROVAL + lints every runAgentLoop callsite for gate overrides.
  • /cost-summary [--since <window>] — segments cost_log by surface + model. Soft-flags chat-% drift past the 68% baseline (cost_tuning_levers) and cache hit % below 60.
  • /dev-server — clean restart for the Next.js dev server. Run any time symptoms hint at competing instances / corrupt .next / port conflicts (404 on routes that exist, broken UI after edit, HMR not picking up). Uses pkill -f not lsof (which silently no-ops; see [dev-server-skill]). Pre-build companion: NO_START=1 bash .claude/skills/dev-server/clean-restart.sh before make-dist.sh per feedback_dont_build_with_dev_running.

Falcon scope

Scope posture is per-tenant. Design the app as wide-open as each tenant allows — gate against actually-granted scopes (capability_gate_pattern), never against a hardcoded baseline. Surfaces self-gate per tenant and degrade to a staged-build banner (nav item hides) where a scope is absent. node scripts/falcon-scope-probe.mjs --all is authoritative per env (decrypts stored creds, mints a token, classifies each scope 403-vs-200; probe the scope's CURRENT endpoint version — a stale path version yields a false 403). Reconcile drift by re-probing, not hand-editing. components/ScopeChecklist.tsx is the in-app source of truth — keep it in sync with the eyas-mcp capability probes in lib/health.ts.

  • Region base-URL gotcha: a tenant's base URL must match its cloud region or it mints a valid token but 401s every call (falcon_tenant_region_base_url).
  • Modules load by default; gating is against API scopes. FALCON_MCP_MODULES is a .env-only escape hatch (note customioa/scheduledreports without underscores).
  • Write tools are approval-gated in chat (lib/mcp/write-tools.ts). DLP creates are Eyas's own (lib/eyas-tools/data-protection.ts, monitor-first); native falcon_create_data_security_entity suppressed, _update_ adopted (both gated). Data Security searches page at 200 (hydrate cap; lib/dataprotection/fetch.ts). Exclusions go through Eyas's tools (extras_*_exclusion, lib/eyas-tools/exclusions.ts; native falcon_create_exclusion stays suppressed), reached through chat only; there is no tuning page.
  • AIDR = eyas-mcp's Guardian module (inherited from falcon-mcp 0.19.0; 25+ read-only tools, falcon_-prefixed live, scope AIDR:read) → dashboard "AI agent activity" tile + /api/guardian. See [[guardian_aidr_surface]].

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.