nano SIEM
Agents & MCPInvestigator

Tool Reference

Supported in:Self-hosted

Every nano-investigator tool, MCP prompt and MCP resource, with permissions and access level

Look up the tools and permissions for @nano-rs/investigator-mcp-server 0.1.16 (main at e5b4043). The server registers 91 tools in 14 groups, five MCP prompts, and 11 MCP resources.

Columns:

  • Access: Read has no side effects. Write creates or changes data. Destructive removes, closes or resets something and can't be undone, so the agent should confirm first.
  • Permission: what the API key needs. Each tool also publishes its requirement in MCP _meta under io.nano/permission-requirements, so clients can show it before calling.

Parameters are required unless marked (opt).

Search and schema (9)

ToolPurposeKey paramsAccessPermission
searchRun an nPL query. The primary search tool.query, start_time; end_time, limit (100), source type (opt)Readsearch:execute
search_sqlRaw SQL SELECT against ClickHouse (read-only identity; audit rows need audit:view)sql; start_time, end_time, limit (opt)Readsearch:sql
get_schemaUDM column inventory (not the OCSF field list)category, include_ext (opt)Readsearch:view, search:execute
explain_queryShow how an nPL query compiles, without running itquery, start_time; end_time (opt)Readsearch:execute
get_field_valuesTop values for a field in a query scopefield, start_time; query, end_time, limit (opt)Readsearch:execute
list_saved_searchesList saved searchesnoneReadsearch:view
get_saved_searchOne saved searchidReadsearch:view
save_searchSave a queryname, query; query_mode, visibility (opt)Writesearch:save
create_shared_searchBuild a shareable UI link for a query and time rangequery; query_mode, time range (opt)Writesearch:share

Alerts (3)

Alerts can't be changed through the server. Triage happens by attaching an alert to a case.

ToolPurposeKey paramsAccessPermission
list_alertsList alerts with filtersall (opt): status, severity, rule_id, assigned_to, limit (50), offsetReadalerts:view
get_alertFull alert, with matched events and ai_triage_hintsidReadalerts:view
get_alert_countsCounts by severity and statusnoneReadalerts:view

Cases (13)

ToolPurposeKey paramsAccessPermission
list_casesList casesall (opt): status[], severity[], assigned_to, search, tags[], limit, offsetReadcases:view
get_caseFull caseidReadcases:view
review_caseCase, wall and every linked notebook in one call. Use it first when resuming a case.id (id or case number)Readcases:view, notebooks:view
get_case_statsCounts by status and severity, average resolutionnoneReadcases:view
get_related_casesSimilar past cases (shared entities, rules, techniques)idReadcases:view
create_caseCreate a casetitle, severity; description, priority, assigned_to, tags[] (opt)Writecases:create
update_caseEdit title, description, severity or tagsid; fields (opt)Writecases:edit
change_case_statusSet status and optional dispositionid, status; disposition (opt)Writecases:edit; cases:close to close or reopen
assign_caseReassignid, user_idWritecases:assign
add_alert_to_caseLink an alertcase_id, alert_id; is_primary (opt)Writecases:edit, alerts:view
add_case_wall_entryPost to the case wallcase_id, entry_type (comment/ai_analysis/action_taken), contentWritecases:comment
merge_notebook_into_caseCopy a notebook's entries into the case notebook and archive the source as merged. If the case has no notebook, the source becomes it and is visible to everyone who can see the case.case_id, source_notebook_idWritecases:view, cases:edit, notebooks:edit
merge_casesMerge source cases into a target; sources are closed as mergedtarget_case_id, source_case_ids[]Destructivecases:edit

Notebooks (9)

ToolPurposeKey paramsAccessPermission
list_notebooksList notebooksall (opt): case_id, status, limit, offsetReadnotebooks:view
get_notebookOne notebookidReadnotebooks:view
get_notebook_entriesA notebook's entriesidReadnotebooks:view
find_notebooks_by_referenceNotebooks that reference an alert, detection, saved search or casereference_type, reference_idReadnotebooks:view
create_notebookCreate a notebooktitle; visibility (opt)Writenotebooks:create
add_notebook_entryAppend an entry (manual_note, search_executed, ai_suggestion, ai_summary, entity_reference, an IOC marker, timeline_marker, investigation_timeline)notebook_id, entry_type, content; source_url (opt)Writenotebooks:edit, or cases:edit for a case notebook
add_notebook_referenceLink a notebook to an objectnotebook_id, reference_type, reference_idWritenotebooks:edit
update_notebookEdit title, status or summaryid; fields (opt)Writenotebooks:edit
share_notebookChange visibilityid, visibility; group_ids[] (opt)Writenotebooks:share

Dashboards (7)

ToolPurposeKey paramsAccessPermission
get_dashboard_schemaThe dashboard document format. Read before authoring.noneReadnone
validate_dashboardCheck a dashboard document locallydashboardReadnone
dashboard_panel_queryRun a panel query the way the panel willquery, query_mode, start_time; end_time (opt)Readdashboards:view + search:execute (nPL)
list_dashboardsList dashboardsscope (my/all) (opt)Readdashboards:view
get_dashboardOne dashboardidReaddashboards:view
create_dashboardCreate a dashboarddashboardWritedashboards:create
update_dashboardReplace a dashboardid, dashboardWritedashboards:edit

Detections and MITRE (5)

The server reads detections; it doesn't write them. Use nanodac to author rules.

ToolPurposeKey paramsAccessPermission
list_detectionsList rulesall (opt): severity, mode, enabledReaddetections:view
get_detectionFull rule: nPL, MITRE, ai_triage_hints, scheduleidReaddetections:view
get_detection_matchesRecent matches for a ruleidReaddetections:view
get_mitre_techniqueATT&CK data, optionally one techniqueid (opt)Readmitre:view
get_mitre_coverageDetection coverage and gapsnoneReadmitre:view, detections:view

Risk (5)

ToolPurposeKey paramsAccessPermission
get_risky_entitiesTop entities by riskall (opt): window, entity_type, min_score, limit (20)Readrisk:view
get_risk_overviewEntity counts by risk level (24h and 7d)noneReadrisk:view
get_entity_risk_timelineRisk over time for one entityentity; entity_type (opt)Readrisk:view
get_entity_risk_activityRecent risk activity for several entitiesentities[] (entity, entity_type)Readrisk:view
reset_entity_riskClear an entity's accumulated risk. The reason is audited.entity, reason; entity_type (opt)Destructiverisk:clear

Enrichment (2)

Threat-intel matches are stamped onto events at ingest as enrichments[] records, so you find them with search (for example enrichments.type="threat_intelligence"). See Enrichment field reference.

ToolPurposeKey paramsAccessPermission
get_entity_contextComposite pivot: geolocation (IPs) and risk timelineentity_type, valueReadrisk:view
lookup_ipGeolocation and ASN for one IPipReadenrichments:view

Prevalence (3)

ToolPurposeKey paramsAccessPermission
get_prevalenceHow common one hash or domain is (IPs aren't accepted)type (hash/domain), valueReadprevalence:view
get_rare_artifactsArtifacts seen on few hostsall (opt): type (hash_md5/hash_sha256/domain/ip_address), window, limit (50), offsetReadprevalence:view
get_new_artifactsArtifacts first seen recentlyall (opt): type, since, limit (50), offsetReadprevalence:view

System (4)

ToolPurposeKey paramsAccessPermission
get_source_typesLog sources with datanoneReadany of search:execute, detections:view, log_sources:create, source_scopes:view
get_org_contextOrg profile: industry, internal ranges, critical assets, hoursnoneReadsettings:view or settings:ai
health_checkCalls /health. Usable only when NANOSIEM_API_URL points straight at the API; behind the edge the path serves the web appnoneReadnone
get_audit_trailQuery the audit log, including this key's own actionsall (opt): user_id, action, resource_type, start_time, end_time, limit (50)Readaudit:view

Parsers (23)

See Build parsers for the workflow and the OCSF output contract.

ToolPurposeAccessPermission
list_log_sourcesList parsersReadlog_sources:view
get_log_sourceFull parser: VRL, metadata, flagsReadlog_sources:view
validate_vrlCompile-check VRLReadlog_sources:view
test_parse_sampleRun VRL on one sample lineReadlog_sources:view
test_parse_liveParse recent real events with new and published VRLReadlog_sources:view, search:execute
get_log_source_draft_statusUnpublished changes, active versionReadlog_sources:view
get_log_source_healthEvent counts, freshness, health_statusReadlog_sources:view
get_log_source_deploymentsRollout history and errorsReadlog_sources:view
create_log_sourceSave a new parser as a working copyWritelog_sources:create
update_log_sourceEdit a working copy (doesn't go live)Writelog_sources:edit
publish_log_sourcePromote the working copy and roll it out. The step that makes an edit live.Writelog_sources:deploy
deploy_log_sourceRe-push the published versionWritelog_sources:deploy
undeploy_log_sourceTake a parser offlineDestructive (stops parsing for that source)log_sources:deploy
list_source_config_typesTransport drivers and match-field presetsReadsource_configs:view
list_source_configsConfigured transportsReadsource_configs:view
check_rule_reachabilityCheck a planned routing ruleReadsource_configs:view
create_routing_ruleRoute matching events to a parserWritesource_configs:edit
deploy_source_configRedeploy a transportWritesource_configs:deploy (+ credentials:use with a credential)
undeploy_source_configTake a transport offlineDestructive (stops that ingest path)source_configs:deploy
list_parser_repositoriesConnected parser repositoriesReadparser_repositories:view
list_repository_parsersBrowse a repositoryReadparser_repositories:view
sync_parser_repositoryRefresh a repositoryWriteparser_repositories:sync
import_parserImport a repository parser as a working copyWriteparser_repositories:import, source_configs:edit

Onboarding (4)

Set up pull-source transports (Kafka, AWS S3/SQS, GCP Pub/Sub).

ToolPurposeAccessPermission
onboarding_requirementsWhat each transport needsReadnone
import_credential_from_fileRead a credential file from the local disk (inside your home or working directory) and store it encryptedWritecredentials:create
create_credentialStore a credentialWritecredentials:create
create_source_configCreate a transport, optionally with routing rulesWritesource_configs:create (+ credentials:use with a credential)

Recon (4)

Profile your log estate and propose hunts.

ToolPurposeAccessPermission
hunt_build_censusStep 1: census of which telemetry is liveReadhunts:profile_write (or hunts:manage)
hunt_huntable_surfaceStep 2: what can be hunted with that telemetryReadhunts:profile_write (or hunts:manage)
hunt_save_profileSave the estate profileWritehunts:profile_write (or hunts:manage)
hunt_propose_draftsCreate draft hunts with opening nPL queriesWritehunts:profile_write (or hunts:manage)

Tools that change state

Everything marked Write or Destructive above. The ones that can't be undone:

  • merge_cases: source cases are closed as merged.
  • reset_entity_risk: the entity's accumulated risk is cleared.
  • undeploy_log_source and undeploy_source_config: ingest for that source stops until redeployed.

Also take care with publish_log_source (changes how new events are parsed) and import_credential_from_file (reads a file from the machine the server runs on).

MCP prompts

Prompts are workflows the agent follows, not tools.

  • investigate_alert (alert_id; depth (opt) quick/standard/deep): read the alert and its detection's ai_triage_hints, assess false vs true positive, enrich entities, search for related activity, check related cases, recommend. See Investigate alerts.
  • hunt_entity (entity, entity_type; time_range (opt), default -24h): context, assessment, then a type-specific deep dive. See Hunt.
  • hunt_campaign (description; time_range (opt), default -7d): plan from a hypothesis, run 3–5 queries, enrich hits, write a hunt report.
  • morning_briefing (hours (opt), default 12): alerts, case load, risky entities, noisy or silent rules and health, as a prioritized shift summary. See Triage & cases.
  • build_parser (source type; sample_log (opt)): the validate-first parser loop. See Build parsers.

MCP resources

URIContent
nanosiem://reference/nplnPL reference
nanosiem://reference/vrl-parsersVRL authoring guide (UDM output contract in 0.1.16)
nanosiem://reference/playbooks/{type}Investigation playbooks: brute_force, lateral_movement, data_exfil, malware, phishing, insider_threat, generic
nanosiem://schema/udmLegacy field reference (not the OCSF schema)
nano://sql-guideSQL guide for search_sql (UDM logs table)

For OCSF fields, point the agent at OCSF field reference instead of the last two.

What's next

On this page