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
In this repository8 other files it gives its agents.
- audit-remediationsSkill
- audit-write-toolsSkill
- cost-summarySkill
- dev-serverSkill
- patch-contextSkill
- validate-bundleSkill
- verify-featureSkill
- verify-patchSkill
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
- Distinctive: line 23
Tenant-relevant, not global catalogs: No flat global lists (50 random actors, full IOC feed) — filter to items with tenant evidence or make …
- Distinctive: line 24
No redundant custom coverage: Don't propose custom IOC / IOA when Falcon Intel / cloud reputation already covers the behavior.
- Distinctive: line 56
Dynamic-group restoration self-heals: Don't try to re-add after removing from quarantine.
≈ “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.
Files
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) andlib/(MCP client, Anthropic client, helpers). Importinglib/llm/orlib/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_iocsprecheck before anyfalcon_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_overlapon QueueRow,campaignson the queue payload,matcheson 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 upstreamfalcon_*tools and routinely ignore even "REQUIRED" instructions for newextras_*tools — seefeedback_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). Seefeedback_user_facing_copy. Sanctioned exception:/agent-toolboxis 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]]./blueprintis 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.tsMAY 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_detectionswithadd_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::describePrimerhumanizes an instruction into a confirmation card (PendingActionCard) + summary bubble; the raw instruction is preserved behind a disclosure. Add a matcher +scripts/test-primer.mjscase per hand-off; no tool names/jargon in title/description (primer_handoff_humanizer). Every launch site routes throughcomponents/primerHandoff.ts::buildPrimerHref, never a bare/?primer=${encodeURIComponent(x)}— primers >~1500 chars overflow the request line and the seeded turn 431s;buildPrimerHrefstashes long ones insessionStorageand passes a short key. - Chat surface = terminal aesthetic, not a feature dashboard.
components/Chat.tsx::EmptyStateis intentionally bare: a$ agent --readymono cap, one declarative paragraph, three›-prefixed starter lines. PlaceholderEyas…. 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.ConversationListis 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 missingresourcesas an empty success — a permission error isscope_pending(staged-build pattern:scope_pending_pattern) and an upstream 400 is an error, notcount: 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 rejectsort=entirely (falconpy_ioa_exclusions_no_sort). NGSIEM management endpoints need explicitrepository/search_domain(ngsiem_management_endpoint_params). RTR class split (falconpy_rtr_method_naming). Threat Graph split by artifact type (threatgraph_hash_only). Custom IOCpreventis hash-only — fordomain/ipv4/ipv6usedetect. 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
sortorder was unstable ≤0.13.0). Search totals: native searches return{results, pagination: {total, …}};projections.ts::searchTotalsHeaderputs 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 wherepaginationsits — without it the agent can't answer "how many" (test:projections). Falcon API 500s arrive asisError: falsetext —tool-bridge.ts::invokerunsparse.ts::detectFalconErroron the agent path so a wrapped 500 becomesisError: true, not an empty success.falcon_search_vulnerabilitiesfacettakes 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_iocsPydantic quirk (falcon_remove_iocs_pydantic_quirk). Spotlight FQLid:[...]rejected on row id (spotlight_row_id_filter_quirk). - NGSIEM CQL —
head(N)notlimit(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 laterhead(N)(ngsiem_sort_default_limit_200). Every NGSIEM search goes through nativefalcon_search_ngsiemwithcheck_cql=true,max_rowsand atime_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: () => falsetorunAgentLoopon a write surface; that REPLACES the registry check entirely. Seefeedback_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 withreadOnlyHint:falseMINUSANNOTATION_GATE_EXEMPT. Do NOT gate rawreadOnlyHint: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-toolboxshows a drift banner (catalog.driftWarnings) if a native write is annotated-but-ungated. Seeannotation_approval_backstop. - IOA exclusion regex — Falcon's IOA DFA engine rejects zero-width assertions (
^,$,\b,\A,\Z,\B).lib/eyas-tools/exclusions.tsruns a pre-flight check on everyifn_regex/cl_regexand fails locally with a useful error before round-tripping to Falcon. Canonical bounding pattern:r"...(\W.*)?"notr"...$". IR-readiness exclusion pattern isr".*\\powershell\.exe(\W.*)?". Seeioa_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-irdeleted 2026-05-02; IR buttons hand off via primer). Scope capture is server-side (detectIrPrimerinapp/api/chat/route.tsinvokes the scope tools before the agent loop + hides them viaIR_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_startvsagent_containedare sacred (Phase 4 only lifts what the agent applied). Per-engagement audit record inir_runs/ir_run_turns.
Falcon Host Groups
- Three group types, two static.
static(by name) andstaticByIDaccept add/remove identically; onlydynamicrejects writes (falcon_host_group_static_by_id). - Host record
groupsfield unreliable — use eyas-mcp'sfalcon_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::enforceToolArgsforcesverify="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 ofLONG_RUNNING_TOOL_TIMEOUT_MSby design. Seefalcon_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, seehost_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 viaAUTO_SAVE_TOOLSinapp/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.tsstrips them). The sidecar's old frozen-env workaround (resolve_group_id/set_runtime_group_id) is gone with it (sidecar_frozen_env_runtime_overrideis history). - Diagnose 404 = group_missing, not raw upstream error. Both
extras_diagnose_quarantine_setupandextras_diagnose_shadow_ai_banned_setupreclassify HTTP 404 on the host-group lookup ascase="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 incl_regex(or its canonical name) — the old comment-substring match never found it. Companion low-level deletes (extras_delete_prevention_policywithdisable_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. Seetenant_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, librarylib/eyas-tools/rtr/library.ts, manifests + scripts underlib/eyas-tools/rtr/{patching,cleanup}/, shipped vianext.config.tsoutputFileTracingIncludes). Eyas validates + renders; ondry_run=falseextras_rtr_run_patch/_run_cleanupcallrunDispatch(lib/mcp/native-dispatch.ts) with the bridge-only natives —falcon_create_rtr_script(private one-offeyas-run-<hex>) →falcon_run_rtr_script_on_hosts→falcon_delete_rtr_scriptsinfinally— and return the oldresults[]shape (cloud_request_id= nativetask_id,exit_codenull);extras_rtr_check_patch_statuspollsfalcon_check_rtr_admin_command_status. The script natives stay hidden inPENDING_NATIVE_MIGRATIONso the agent can never upload bytes. - Render-time security in
lib/eyas-tools/rtr/library.ts— agent supplies validatedid+ params, never script bytes.validateParamsenforces enum + regex per manifest schema (Pythonrepatterns run as JS: fullmatch anchoring, leading(?i)→iflag, no other inline flags);asciiCoerceis the render-time backstop (RTR transport mangles non-ASCII under SYSTEM) and must keep?— the Python version stripped every?, breakingrc=$?and query-string URLs.test:rtr-librarycovers it. - Manifest ordering matters. First-declared-wins;
win-wsl-updatebeforewin-update-install. Run/audit-remediationsafter any manifest change — per-script/verify-patchcan'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-uninstallwalks registry for legacy Oracle/Sun JRE 6/7/8 only. - MCP 60s timeout caps batch_admin_command (
mcp_timeout_vs_falcon_wait) — runs passtimeout_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 viaextras_rtr_check_patch_status. Tools that legitimately block longer than 60s (currently eyas-mcp'sfalcon_wait_for_rtr_sessions, the Phase 1.5 propagation wait;enforceToolArgsalways setsprobe="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 viaLONG_RUNNING_TOOL_TIMEOUT_MSintool-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 (seefalcon_host_groups_field_unreliablefor the canonical fix). - Falcon-published RTR scripts: server SKU quirks (
falcon_scripts_workstation_quirks). Token defense:projectFalconScriptRuncaps 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. Seesubagent_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/investigatecan share the native client behindEYAS_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.
runSubAgentrejects any name inREQUIRES_APPROVALfrom the filter regardless of caller intent./audit-write-toolsgreps for this. - Sub-agents collect, parent route forwards synthetic
tool_use+tool_resultevents AFTER completion with namespaced ids. - Per-slice surface attribution (
investigate:fingerprintetc.) inlib/cost/log.ts.
Shadow-AI
- IOA needs installer rules, not just launch rules (
shadow_ai_ioa_installer_rules). extras_shadow_ai_check_prevention_bindingdiagnoses 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 bycomponents/irEligibility.tsx::IrChip— the chip is ALWAYS shown with three explicit states: eligible / ineligible-with-tooltip / off→links to /config./queueuses the same predicate (the prior Linux-gets-IR queue bug is fixed). Lenient on sparse data; surfaces that aren't detection-triage passshowIr={false}. Seeir_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, notrequest.signal.lib/chat/stream-agent.tscreates AbortController, hands signal to ctx, aborts oncancel().runAgentLoopchecks 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 threadsignalthrough.awaitApprovalis also signal-aware (lib/chat/approvals.ts): a disconnect/Stop during a pending write-approval resolves it immediately astimeoutinstead 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 schemaexamples/enum/requiredin a different order per Python process (and in dev it starts per turn), sobuildToolBridgereturns 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/healthzis the cheap public liveness probe (no upstream calls) — suitable for orchestrator + uptime monitors./api/healthis full diagnostics (Anthropic + Falcon MCP + extras probes) and is authenticated;?force=1triggers a fresh fanout behind the same auth gate.getHealthReport()cached for 30s with in-flight de-dup. instrumentation.tsNode-only imports insideif (process.env.NEXT_RUNTIME === "nodejs")(instrumentation_runtime_guard).- Anthropic gateways 404 on
/v1/models(gateway_models_endpoint) —lib/health.ts::probeAnthropicdowngrades to ok-with-note whenANTHROPIC_AUTH_TOKENis set. - Conversation history + resume (claude.ai-style) —
chat_sessionstable; 72h rolling idle TTL is the single source of truth inlib/chat/state.ts::TTL_MS(route emitssession_stateSSE withexpiresAt)./chatmounts fresh — no auto-resume; resumable only via theConversationListpop-out drawer. Pending approvals survive resume (listPendingForSessionrestamps). Full detail inchat_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>notbusystate (state updates lag back-to-back calls). - Markdown overflow defenses —
.markdown tableisdisplay: block; overflow-x: auto; useoverflow-wrap: break-wordNOTanywhere/word-break: break-word(splits10.20.30.40). - Next.js
unstable_cache2MB limit (unstable_cache_2mb_limit) — vuln payloads bust it silently; use module-scoped Map. - HOSTNAME quirk on macOS standalone — zsh auto-exports;
start.shforcesHOSTNAME=127.0.0.1. - Session cookie
Securekeys offx-forwarded-proto, NOTNODE_ENV— bothlib/auth/session.tsandmiddleware.tsderivesecurefrom the request scheme. The standalone bundle runsNODE_ENV=productionover plain HTTP, where aSecurecookie is silently dropped and rolling-renewal logs the operator out. A TLS-terminating proxy setsx-forwarded-proto=httpsso real HTTPS deploys still getSecure. Don't "fix" this back toNODE_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 guessedname:~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.shstripscom.apple.quarantine(Gatekeeper on unsigned.node) AND picks the matching better-sqlite3 prebuild fromvendor/better-sqlite3-prebuilds/<target>-<abi>/based on the recipient'sprocess.versions.modules.make-dist.shstages one prebuild per supported ABI (currently 127 Node 22, 137 Node 24) from upstream WiseLibs Releases. Adding a new Node LTS = append toBSQLITE_ABIS=(…); may require a better-sqlite3 major bump. - Standalone install — bundle ships
install.sh(fromscripts/gen-install.sh, quoted-template so$HOMEresolves on the recipient, never the builder) →eyaslauncher in~/.local/bin(start/stop/restart/status/logs). No in-app update (removed 0.9.1): upgrading = running a newer bundle'sinstall.sh(rsync preserves.env+data/). eyas does NOT use the sharedmacos-standalonegenerator (builder-$HOME+nohup _nodebugs). 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) —guardChatCompletionsreturns{status, result: {blocked, detectors, ...}}; read atresp.result.*notresp.*. Detector keys:malicious_prompt,confidential_and_pii_entity,secret_and_key_entity, etc. — gate ondetected: true(noactionfield). - DB WAL checkpoint on shutdown (
db_wal_checkpoint_on_shutdown) —lib/db/client.tsregisters SIGTERM/SIGINT/SIGHUP/beforeExit →wal_checkpoint(TRUNCATE)+close(). Without it, every kill leaves writes only ineyas.db-waland the main file stays at ~12 KB. SQLite auto-checkpoint at 1000 pages is well above what this app accumulates. tool-bridge.invokereturnscontentas a string (tool_bridge_content_is_string) — joined MCP blocks, NOT the rawArray<{type,text}>.onToolResultcallbacks 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 asisError: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::isScopeDeniedkeys onstatus_code/required_scopes/scope_pending(substring fallback); shared byhealth.tsprobes + cases/quarantine/correlation/data-protection routes + snapshot. Keep the nav gate and the page on the same helper. Block-awareparseToolResultObjects(content)parses each MCP block directly (agent path only; dashboards keepparseConcatenatedJson).
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/sdk1.3.0, API version2026-10-21). SDK 1.x holds one credential per client and sends an API key as Bearer;anthropicClientOptionskeeps Eyas's old wire headers (API key asX-Api-Key, token as Bearer, both when both are set) so gateways see no change — everynew Anthropic(...)goes through it. Every Claude request goes throughlib/llm/messages.ts::createMessage/streamMessage(beta Messages namespace) — neverclient.messages.*directly. They applylib/llm/request.ts::withModelDefaults:max_tokensfloor of 16K (thinking counts against it on the 5.5 generation — the old 1K–8K per-route caps truncate), explicitoutput_config.effort: "medium"only where the model accepts it (not Haiku 4.5 / Sonnet 4.5 / older), and server-side refusal fallbacks (fallbacks: "default", betaserver-side-fallback-2026-07-01) onclaude-opus-5-5/claude-sonnet-5-5only. 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 withassistantTurnContentand run tools fromtoolUsesToRun:fallbackblocks stay in place unchanged; thinking / tool_use / unpaired server-tool blocks BEFORE the lastfallbackblock are dropped (the API rejects them). Default modelclaude-sonnet-5-5(lib/config/runtime.ts),claude-opus-5-5the higher-quality option. Never sendtemperature/top_p/thinking: disabled/budget_tokens/ forcedtool_choice/ assistant prefill — all 400 on the 5.5 models; keepmessagesappend-only (thinking blocks are passed back unchanged;chat_sessionsstores them verbatim). Astop_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 inlib/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 setsNATIVE_WRITE_SUPPRESS/NATIVE_READ_KEEP/PENDING_NATIVE_MIGRATION,enforceToolArgs(forcesverify="static"on group membership andprobe="runscript"onfalcon_wait_for_rtr_sessions), long-call timeouts inLONG_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'dispatchenvelopes 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— reusesbuildToolBridgeso it can't drift from what the agent sees; globalThis-TTL-cached likelib/health.ts).lib/prevention/posture.ts— prevention posture for/prevention, home, Shadow-AI setup and the snapshot fromfalcon_get_prevention_posture, with Eyas's detect-only rule (onlyOnSensorMLSlider/CloudAntiMalwarecount).projections.tsrenders 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-toolduration_ms, optionaltoolFilter),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;ApprovalButtonsreads sessionId from localStorage),state.ts(carriesIrMode { aid, startedAt, recordPath, turnCount }per session),ir-run-record.ts(per-IR-session record backed byir_runs+ir_run_turnstables; basename<aid>-<startedAt>.jsonis the URL slug and lookup key;recentIrCostProjectionfor kickoff projection).Decisionis"allow" | "deny" | "timeout".lib/scheduler/— manifest-driven recurring-job runtime. Add: one file underlib/scheduler/jobs/+ one line inindex.ts. Registered:patch-digest,daily-briefing,release-watcher(compares theversions.jsoneyas-mcp pin withGTStagg/eyas-mcpmain 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 thecost_logtable indata/eyas.db.logUsage()fire-and-forget.lib/db/— SQLite (better-sqlite3) + Drizzle ORM (queries) + custom SQL migration runner.client.tsglobalThis-pinned WAL handle.crypto.tsAES-256-GCM column encryption (HKDF fromAUTH_SESSION_SECRET; rotating the secret intentionally invalidates encrypted creds — see [db-column-encryption-contract]).migrate.tsforward-only with checksum drift + downgrade trap + pre-migrate backup (see [db-migration-runner-safety]).bootstrap.tsawaited byinstrumentation.tsperstandalone_secret_warmup_blocking. Migrations live as numbered .sql files; never edit a shipped one — add000N_<name>.sqlfor changes. 0.3.0 squashed prior migrations into a single0001_init.sqlbaseline; fresh-install only.lib/auth/—store.ts(Nodecrypto.scrypt→ single-rowauthtable indata/eyas.db) +session.ts(iron-session, 7-day rolling). Rootmiddleware.tsgates everything except/login,/register,/api/auth/*,/api/healthz, static./api/healthis authed.lib/config/—store.tsis single owner of thesettings+environmentstables indata/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.tsdelegate..envis 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). EverymutateSettings()runs in one atomic transaction across settings + environments + the SQL-trigger-enforced append-onlysettings_audittable. Active-env switch refused with 409 whilelib/chat/in-flight.ts::isBusy()is true.- Secrets at rest: Falcon + Anthropic creds AES-256-GCM column-encrypted in
data/eyas.db(mechanism inlib/db/above); DB file mode 0600. The macOS-Keychain / node-keytar variant was rejected because target Macs block the native.nodebinary. See [db-column-encryption-contract]. - Build-time deployment lock:
lib/config/build-flags.tsexportsBUILD_FLAGS = { gatewayOnly, forcedGatewayUrl }. Dev defaultsfalse/null;make-dist.shoverwrites beforenpm run buildto 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+.envprotects against other Unix users on the box. An exfiltrated DB alone is unreadable — the attacker also needsAUTH_SESSION_SECRETfrom.env(the HKDF root). Residual risks: backup hygiene (a synced folder capturing BOTHdata/and.envdefeats the separation), no graceful re-key forAUTH_SESSION_SECRETrotation (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 bytool-bridge.ts(they replaced the old sidecar tools of the sameextras_*name).EyasTool= name + description + input schema +run(input, {callNative}); any Falcon call goes through eyas-mcp natives viacallNative. Register inindex.ts; classify inwrite-tools.ts(test:tool-classificationenforces it). Today: the four workflow playbooks (playbooks/*.tstext; 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, overfalcon_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; pagedfalcon_search_detections, closes viafalcon_update_detections500 ids at a time; the AI-egress list the IR classifiers and the Shadow-AI hunts share isai-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_precedencewithmove_id+place_first, readiness exclusion viafalcon_create_exclusionwithskip_if_duplicate), the Shadow-AI hunts (shadow-ai/hunt.tsover the catalog inshadow-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 beforefalcon_create_exclusion), the Data Protection creates (data-protection.ts: monitor-first bodies overfalcon_create_data_security_entity;test:exclusionscovers both), Shadow-AI setup and prevention (shadow-ai/prevention.ts: banned group diagnose / create / adopt, policy provisioning placed after the IR quarantine policy viafalcon_set_policy_precedenceplace_after, rule-group status, the binding check, and the adopt that authors the per-platform Custom IOA corpus inshadow-ai/ioa-corpus.jsonand converges rules with one batchedfalcon_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 nativefalcon_get_process_treeand run Eyas's delivery-vector classifier inprocess-tree/classifier.tsover its nodes; the remote-access-tool scan is one boundedfalcon_search_ngsiem;test:process-tree). Tools that need rows from a native search usectx.searchNative.- No Python in Eyas itself. The sidecar, its venv, its wheels,
test:sidecarand its deploy verification (expected_tools.json,verify_tools.py, the/statusadd-on row) are gone;/validate-bundlefails a bundle that carries anyfalcon-extras/file. The only Python is eyas-mcp, run byuvx(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(/intelpage-level adversary graph),adversary.ts(per-row chip enrichment —extractAdversaryIds+enrichRowsWithAdversarybatch-resolve via onefalcon_search_actorscall).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 vialib/discover/native.ts::fetchDiscoverSnapshot(shared with the posture snapshot): assets fromfalcon_search_assets(eyas-mcp ≥ 7fd4031) as two calls merged bynormalizeAssetSearch— every entity type withinclude_type_totals(tenant-wide managed / unmanaged / unsupported / other counts →breakdown,otherTypes), plus anentity_type:'unmanaged'sample for the coverage-gap list — applications fromfalcon_search_applicationswith NO filter (no match-all filter exists —name:'*'silently returns 0) andfields:"compact", accounts fromfalcon_search_accounts. Results are shaped bylib/mcp/native-shape.ts. Capability gate isFalconMcpCapabilities.discover. See [[falcon_scope_probe_and_discover]].scripts/falcon-scope-probe.mjs— live per-environment API-posture probe; authoritative reconciliation forcomponents/ScopeChecklist.tsxdrift (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 viatests/auth.setup.tssealing a session cookie usingAUTH_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-levelversionfields ofpackage-lock.json, the README lead line (**vX.Y.Z**), and renames CHANGELOG## Unreleasedto## X.Y.Z — <one-line theme>. Run/audit-write-toolsbefore 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 againstREQUIRES_APPROVAL+ lints everyrunAgentLoopcallsite for gate overrides./cost-summary [--since <window>]— segmentscost_logby 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). Usespkill -fnotlsof(which silently no-ops; see [dev-server-skill]). Pre-build companion:NO_START=1 bash .claude/skills/dev-server/clean-restart.shbeforemake-dist.shperfeedback_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_MODULESis a.env-only escape hatch (notecustomioa/scheduledreportswithout 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); nativefalcon_create_data_security_entitysuppressed,_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; nativefalcon_create_exclusionstays 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, scopeAIDR:read) → dashboard "AI agent activity" tile +/api/guardian. See [[guardian_aidr_surface]].
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
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.

