# Nebulock Documentation

> Nebulock is a threat hunting platform designed to surface endpoint and identity-based threats. Explore the documentation for supported ingestion sources, integrations, and feature implementation.

## Guides
- [About Nebulock](https://docs.nebulock.io/docs/overview.md)
- [Access Nebulock](https://docs.nebulock.io/docs/access.md)
- [Okta SAML SSO](https://docs.nebulock.io/docs/okta-saml-single-sign-on.md): How to create an Okta application to connect to the Nebulock portal via Single Sign On (SSO).
- [Entra SAML SSO](https://docs.nebulock.io/docs/entra-saml-single-sign-on.md): How to set up Single Sign On (SSO) for EntraID SAML.
- [Connect Your Data Sources](https://docs.nebulock.io/docs/connecting-your-data-sources.md)
- [AWS CloudTrail](https://docs.nebulock.io/docs/aws-cloudtrail.md): You can integrate with AWS CloudTrail as a telemetry source with an S3 bucket and SNS. We use a CloudFormation template to provision the necessary resources and grant our worker role read-only access to ingest logs. This ensures your data remains in your control while allowing us to provide security insights.
- [Crowdstrike API](https://docs.nebulock.io/docs/crowdstrike-ng-siem-api.md): The Crowdstrike NGSIEM integration pulls Endpoint Event data and Alert data from Crowdstrike using the NGSIEM API.
- [Crowdstrike FDR](https://docs.nebulock.io/docs/crowdstrike-fdr.md): The Crowdstrike Falcon Data Replicator integration connects to your FDR feed to ingest Endpoint Event data into the Nebulock platform.
- [Duo](https://docs.nebulock.io/docs/duo.md): The Duo integration ingests login and user activity logs into Nebulock for usage in creating Findings as well as adding context to Findings.
- [Github](https://docs.nebulock.io/docs/github.md): The Github integration enables you to push rules you have created in Nebulock to a Github repository you control.
- [Jira](https://docs.nebulock.io/docs/jira.md): The Jira integration is used to connect your Jira instance to the Nebulock platform. This integration allows for the creation of tickets in your specified Jira project from Nebulock Findings.
- [Microsoft Defender and Entra](https://docs.nebulock.io/docs/microsoft-defender-and-entra.md): The setup for Microsoft Defender and Microsoft Entra are the same. The Microsoft Defender integration will ingest Endpoint Event data and Alert data into the Nebulock platform, while the Microsoft Entra integration will ingest IAM data (authentication logs, activity logs) into Nebulock.
- [Microsoft Event Hub](https://docs.nebulock.io/docs/microsoft-event-hub.md): Documentation for setting up an Azure Event Hub to send telemetry to Nebulock.
- [Microsoft Sentinel](https://docs.nebulock.io/docs/microsoft-sentinel.md): The Microsoft Sentinel integration pushes Nebulock security findings directly into Microsoft Sentinel. We use Microsoft's latest **Logs Ingestion API** (via Data Collection Rules).
- [Microsoft Teams](https://docs.nebulock.io/docs/microsoft-teams.md): The Microsoft Teams integration will enable pushing Findings to a Teams channel via a Workflow.
- [Okta](https://docs.nebulock.io/docs/okta.md): The Okta integration will ingest user authentication and activity logs into Nebulock, to generate Findings as well as add IAM context to existing Findings.  <Callout icon="📘" theme="info">  </Callout>
- [SentinelOne API](https://docs.nebulock.io/docs/sentinelone-api.md): The SentinelOne API integration enables querying Endpoint Event data from SentinelOne XDR and ingesting it into the Nebulock Platform.
- [Slack](https://docs.nebulock.io/docs/slack-integration.md)
- [Splunk HEC](https://docs.nebulock.io/docs/splunk-hec.md): The Splunk integration pushes Findings data in JSON format to Splunk via the HTTP Endpoint Collector.
- [Tines](https://docs.nebulock.io/docs/tines.md): The Tines integration works by sending data to a Tines webhook. This integration will push Nebulock Findings to your Tines platform and into your existing Tines Stories.
- [Configure Your Context](https://docs.nebulock.io/docs/configure-your-context.md)
- [Vibe Hunting](https://docs.nebulock.io/docs/vibe-hunting.md)
- [Hunt Modes](https://docs.nebulock.io/docs/hunt-modes.md): Customize how you engage with the vibe hunt agent to achieve hunt goals.
- [Write Your First Detection Rule](https://docs.nebulock.io/docs/write-your-first-detection-rule.md): Detection rules allow users to create signals for events of interest that are derived from threat intelligence or the output of hunts.
- [Deploy Your First Detection Rule](https://docs.nebulock.io/docs/deploy-your-first-detection-rule.md)
- [Run Your First Retrohunt](https://docs.nebulock.io/docs/run-your-first-retrohunt.md)
- [Run Your First Simulated Attack](https://docs.nebulock.io/docs/run-your-first-simulated-attack.md)
- [Leverage Threat Intel Reports](https://docs.nebulock.io/docs/leverage-threat-intel-reports.md)
- [Review Findings](https://docs.nebulock.io/docs/review-findings.md)
- [Insights](https://docs.nebulock.io/docs/insights.md)
- [Create an API Key](https://docs.nebulock.io/docs/create-an-api-key.md)
- [Create a Hunt Report](https://docs.nebulock.io/docs/create-a-hunt-report.md)
- [Anomalies](https://docs.nebulock.io/docs/anomalies.md): The Anomalies Dashboard provides visibility into activity across the organization that deviates from a calculated baseline. This is a great starting point for identify suspicious behaviors.
- [MITRE Coverage](https://docs.nebulock.io/docs/mitre-coverage.md): The MITRE Coverage dashboard displays an overview of rules written and deployed by Nebulock, providing insight into current coverage across MITRE Tactics and Techniques.
- [Add to the Knowledge Base](https://docs.nebulock.io/docs/add-to-the-knowledge-base.md): Knowledge Base is a repository for internal context that will enhance the agent's hunt capabilities.
- [Help](https://docs.nebulock.io/docs/help.md): Ways to get help with Nebulock.
- [Security ](https://docs.nebulock.io/docs/security.md)

## API Reference
- [Get started with the Nebulock Findings API](https://docs.nebulock.io/reference/getting-started-with-the-nebulock-findings-api.md)
- [Get Details of a Finding](https://docs.nebulock.io/reference/get_finding_with_details_api_v2_findings__finding_id__get.md): Retrieve the details for a specific finding.
- [Update a Finding](https://docs.nebulock.io/reference/update_finding_api_v2_findings__finding_id__patch.md): Update an existing finding and return the updated finding.
- [Get a List of Findings](https://docs.nebulock.io/reference/list_findings_api_v2_findings_get.md): Retrieve all findings within an organization. The return list of findings includes pagination metadata.
- [Get Comments in a Finding](https://docs.nebulock.io/reference/get_finding_comments_api_v2_findings__finding_id__comments_get.md): Retrieve the comments for a finding.
- [Create Finding Comment](https://docs.nebulock.io/reference/create_finding_comment_api_v2_findings__finding_id__comments_post.md): Create a comment for a finding.
- [Get a List of Actors](https://docs.nebulock.io/reference/get_actors_public_v1_entities_actors_get.md): Retrieve a list of actors from your organization. Each actor includes its **description**, **risk_level**, linked users, and linked hosts.Use filters to narrow results, or `search_text` for keyword search across indexed actor text.
- [Create an Actor](https://docs.nebulock.io/reference/create_actor_public_v1_entities_actors_post.md): Create a new actor. Request body is an **ActorCorrelation** object (not wrapped in a property). Provide a**description** that explains the person or entity, and a **risk_level** (`high`, `low`,or `escalated`) so automated agents can prioritize correlated content. Optional fieldsinclude `primary_entity_id`, `primary_entity_type`, `user_identifier`, tags, and groups.Omit `actor_id` to receive a server-generated ID. When `risk_level` is `escalated`, set`escalated_till` to a future UTC timestamp.
- [Get an Actor](https://docs.nebulock.io/reference/get_actor_public_v1_entities_actors__actor_id__get.md): Get one actor by ID.Returns the actor's **description**, **risk_level**, and all linked users and hosts.
- [Update Actor Description](https://docs.nebulock.io/reference/update_actor_description_public_v1_entities_actors__actor_id__patch.md): Update an actor.Include at least one of: **description**, **risk_level**, **tags**, **nebulock_tags**,**groups**, **user_identifier**, or **escalated_till**.**description**: Omit the key or send JSON ``null`` to leave unchanged; send ``""`` to clear.Automated agents use the description when reasoning about this actor's correlated content.**risk_level**: One of ``high``, ``low``, or ``escalated``. Omit, ``null``, or ``""`` to leaveunchanged. Agents use risk level together with the description to prioritize handling.When setting ``escalated``, provide a future **escalated_till** (UTC).
- [Create Populated Actors](https://docs.nebulock.io/reference/create_populated_actors_public_v1_entities_actors_populated_post.md): Bulk-create actors with linked users and hosts from flat rows. A spreadsheet format is recommended for identity data (one row per person or endpoint).Rows that resolve to the same user identity (email, username, or endpoint UID) mergeinto a single actor. Optional **description** on each row is stored on the actor andused by automated agents together with the actor's **risk_level**.Hosts are matched by **endpoint_uid** only; **host_name** does not merge hosts across rows.
- [Update Actor Search](https://docs.nebulock.io/reference/update_actor_search_public_v1_entities_actors__actor_id__update_search_index_patch.md): Refresh an actor's search index.  Rebuilds the indexed text used by keyword search from the actor's description, linked users, hosts, and tags. Call after bulk changes to users, hosts, or actor metadata.
- [Associate User With Actor](https://docs.nebulock.io/reference/associate_user_with_actor_public_v1_entities_actors__actor_id__users__user_id__post.md): Link an existing user to an actor.  Returns the actor with updated linked users and hosts.
- [Update Actor User API](https://docs.nebulock.io/reference/update_actor_user_api_public_v1_entities_actors__actor_id__users__user_id__patch.md): Update a user linked to an actor.  Same request body as ``PATCH /users/{user_id}``. The user must already be linked to this actor. Returns the actor with reloaded users and hosts.
- [Unlink User From Actor](https://docs.nebulock.io/reference/unlink_user_from_actor_public_v1_entities_actors__actor_id__users__user_id__delete.md): Remove a user from an actor.  The user record remains in your organization; only the link to this actor is removed.
- [Unlink Host From Actor](https://docs.nebulock.io/reference/unlink_host_from_actor_public_v1_entities_actors__actor_id__hosts__host_id__delete.md): Remove a host from an actor.  The host record remains in your organization; only the link to this actor is removed.
- [Associate Host With Actor](https://docs.nebulock.io/reference/associate_host_with_actor_public_v1_entities_actors__actor_id__hosts__host_id__post.md): Link an existing host to an actor.  Returns the actor with updated linked users and hosts.
- [Update Actor Host API](https://docs.nebulock.io/reference/update_actor_host_api_public_v1_entities_actors__actor_id__hosts__host_id__patch.md): Update a host linked to an actor.  Same request body as ``PATCH /hosts/{host_id}``. The host must already be linked to this actor. You may send ``host_name`` or ``description`` for the display name. Returns the actor with reloaded users and hosts.
- [Create Host For Actor API](https://docs.nebulock.io/reference/create_host_for_actor_api_public_v1_entities_actors__actor_id__new_host_post.md): Create a host and link it to an actor.  If ``host_name`` is omitted, the display name defaults to ``New Host``. Returns the actor including the new host.
- [Create User For Actor API](https://docs.nebulock.io/reference/create_user_for_actor_api_public_v1_entities_actors__actor_id__new_user_post.md): Create a user and link it to an actor.  If ``user_name`` is omitted, the display name defaults to ``New User``. Returns the actor including the new user.
- [Update Host Record](https://docs.nebulock.io/reference/update_host_record_public_v1_entities_hosts__host_id__patch.md): Update a host by ID.  Send ``host_name`` or ``description`` for the display name, plus any of ``endpoint_uid``, ``high_risk``, ``tags``, or ``groups``.
- [Get a List of Users](https://docs.nebulock.io/reference/get_users_public_v1_entities_users_get.md): List identity users for your organization.  Users may be linked to zero or more actors. Use ``correlation_state`` to filter by linkage.
- [Create Users](https://docs.nebulock.io/reference/create_users_public_v1_entities_users_post.md): Create one or more users.  Request body is a **JSON array** of user objects (up to 1000). A single-element array returns one user in ``data``; multiple elements return a paginated list with ``meta`` and ``data``. Link users to actors with ``POST /actors/{actor_id}/users/{user_id}`` or bulk ``POST /actors/populated``.
- [Update User](https://docs.nebulock.io/reference/update_user_public_v1_entities_users__user_id__patch.md): Update a user by ID.  Send at least one supported field, such as ``high_risk``, ``user_name``, ``user_email``, ``tags``, or ``groups``.
- [Get a List of Hosts](https://docs.nebulock.io/reference/get_hosts_public_v1_entities_hosts_get.md): List hosts (endpoints or machines) for your organization.  Hosts may be linked to zero or more actors. Use ``correlation_state`` to filter by linkage.
- [Create Hosts](https://docs.nebulock.io/reference/create_hosts_public_v1_entities_hosts_post.md): Create one or more hosts.  Request body is a **JSON array** of host objects (up to 1000). A single-element array returns one host in ``data``; multiple elements return a paginated list with ``meta`` and ``data``. Link hosts to actors with ``POST /actors/{actor_id}/hosts/{host_id}`` or bulk ``POST /actors/populated``.
- [Get started with the Nebulock Hunts API](https://docs.nebulock.io/reference/get-started-with-the-nebulock-hunts-api-1.md)
- [Generate hunt suggestions](https://docs.nebulock.io/reference/generate_hunt_suggestions_public_v1_hunt_suggestions_post.md): Generate hunt suggestions based on threat intelligence context.
- [List hunt suggestions](https://docs.nebulock.io/reference/list_hunt_suggestions_public_v1_hunt_suggestions_get.md): Retrieve a paginated list of hunt suggestions.
- [Get hunt suggestions by job ID](https://docs.nebulock.io/reference/get_hunt_suggestions_by_job_public_v1_hunt_suggestions_jobs__job_id__get.md): Retrieve hunt suggestions for a specific job.
- [Get hunt suggestion by ID](https://docs.nebulock.io/reference/get_hunt_suggestion_public_v1_hunt_suggestions__hunt_suggestion_id__get.md): Retrieve a single hunt suggestion by ID.
- [Get hunt agent versions](https://docs.nebulock.io/reference/get_hunt_agent_versions_public_v1_hunt_agent_versions_get.md): Returns available agent versions, supported modes per version, defaults, and deprecation status.
- [List hunt reports](https://docs.nebulock.io/reference/list_hunt_reports_public_v1_hunt_reports_get.md): Retrieve a paginated list of hunt reports.
- [Get a hunt report by ID](https://docs.nebulock.io/reference/get_hunt_report_public_v1_hunt_reports__hunt_report_id__get.md): Retrieve a single hunt report with markdown content.
- [Download hunt report PDF](https://docs.nebulock.io/reference/get_hunt_report_pdf_public_v1_hunt_reports__hunt_report_id__pdf_get.md): Download the hunt report as a PDF file.
- [Retry a failed hunt report](https://docs.nebulock.io/reference/retry_hunt_report_public_v1_hunt_reports__hunt_report_id__retry_post.md): Retry generation of a failed hunt report.
- [List hunts (v2)](https://docs.nebulock.io/reference/list_hunts_v2_public_v2_hunts_get.md): Retrieve a paginated list of hunts. Default source filter is 'manual'.
- [Create a new hunt (v2)](https://docs.nebulock.io/reference/create_hunt_v2_public_v2_hunts_post.md): Create a hunt with async directive processing.
- [Get hunt by ID (v2)](https://docs.nebulock.io/reference/get_hunt_v2_public_v2_hunts__hunt_id__get.md): Get a hunt with directives, blocks, and user enrichment.
- [Generate hunt report (v2)](https://docs.nebulock.io/reference/generate_hunt_report_v2_public_v2_hunts__hunt_id__generate_report_patch.md): Trigger report generation for a hunt.
- [Get directive by ID (v2)](https://docs.nebulock.io/reference/get_directive_v2_public_v2_hunts__hunt_id__directives__directive_id__get.md): Get a directive with blocks and user enrichment.
- [Add directive to hunt (v2)](https://docs.nebulock.io/reference/add_directive_v2_public_v2_hunts__hunt_id__directives_post.md): Add a new directive (follow-up query) to an existing hunt.
- [Retry failed directive (v2)](https://docs.nebulock.io/reference/retry_directive_v2_public_v2_hunts__hunt_id__directives__directive_id__retry_post.md): Retry a directive that has failed processing.
- [Stop processing directive (v2)](https://docs.nebulock.io/reference/stop_directive_v2_public_v2_hunts__hunt_id__directives__directive_id__stop_post.md): Stop a directive that is currently being processed.
- [List hunt report feedback](https://docs.nebulock.io/reference/list_hunt_report_feedback_v2_public_v2_hunt_reports__hunt_report_id__feedback_get.md): List append-only feedback rows for a completed hunt report (oldest first, chronological).
- [Create hunt report feedback](https://docs.nebulock.io/reference/create_hunt_report_feedback_v2_public_v2_hunt_reports__hunt_report_id__feedback_post.md): Create append-only feedback for a completed hunt report.
- [Update a hunt (v2)](https://docs.nebulock.io/reference/update_hunt_v2_public_v2_hunts__hunt_id__patch.md): Update a hunt's properties.
- [Validate Rule Public Api](https://docs.nebulock.io/reference/validate_rule_public_api_public_v1_rules_validate_post.md): Validate rule content without persisting a rule.  Use this to check Sigma YAML or SQL payloads before calling `POST /rules`. For Sigma rules, send `content` as a YAML string. For SQL-based types, send `content` as an object with `query`, `schedule`, and type-specific fields. The alias `rule_content` is accepted in place of `content`.
- [Create Rule Public Api](https://docs.nebulock.io/reference/create_rule_public_api_public_v1_rules_post.md): Create a rule in your organization.  One endpoint handles all supported `rule_type` values; the shape of `content` must match the type (see request examples in this operation).  | `rule_type` | `content` format | Notes | |---|---|---| | `sigma` | YAML **string** or parsed Sigma object | Title/description/tags can live in the YAML. | | `scheduled_sql` | Object with `query`, `schedule`, `entity_fields` | Query must contain `organization_id = ?`. | | `signal_combination` | Object with `query`, `schedule`, `description` | Customer portal org only on this API. |  **Organization ID:** External callers should omit `organization_id` — the rule is created under the organization in your session. Internal portal sessions may pass `organization_id` (use `"*"` for cross-tenant rules when omitted on internal portal).  **Status:** Use `inactive` while iterating; set `active` when ready to deploy.
- [List Rules Public Api](https://docs.nebulock.io/reference/list_rules_public_api_public_v1_rules_get.md): List rules for the authenticated organization.  Results are always scoped to the organization in your Nebulock session (you cannot list another tenant's rules). Use `limit` / `offset` for pagination and `version` to control which rule versions are returned (`latest`, `all`, or a specific number).
- [Get Rule Public Api](https://docs.nebulock.io/reference/get_rule_public_api_public_v1_rules__rule_id__get.md): Get a rule by ID.  Returns the latest version when `version` is omitted; pass a version number to fetch a specific revision. The rule must belong to your session organization.
- [Delete Rule Public Api](https://docs.nebulock.io/reference/delete_rule_public_api_public_v1_rules__rule_id__delete.md): Delete a rule (all versions) in your organization.
- [Update Rule Public Api](https://docs.nebulock.io/reference/update_rule_public_api_public_v1_rules__rule_id__patch.md): Update a rule in your organization.  Send only fields you want to change. `user_id` is taken from your session and cannot be set via the public API. Updating `content` replaces the typed content for the rule's `rule_type` (same shapes as create).
- [Test Sql Rule Public Api](https://docs.nebulock.io/reference/test_sql_rule_public_api_public_v1_rules__rule_id__test_sql_rule_post.md): Run an on-demand test execution for a `scheduled_sql` rule in your organization.
- [Run Rule Scheduled Sase Public Api](https://docs.nebulock.io/reference/run_rule_scheduled_sase_public_api_public_v1_rules__rule_id__runs_post.md): Trigger a retroactive run of a `scheduled_sql` rule.  Internal portal sessions execute under the customer portal organization so runs use tenant data and ClickHouse grants.
- [Get Rule Runs Scheduled Sase Public Api](https://docs.nebulock.io/reference/get_rule_runs_scheduled_sase_public_api_public_v1_rules__rule_id__runs_get.md): List scheduled-sase runs for a `scheduled_sql` rule (metadata only, no row results).
- [Get Rule Run Results Scheduled Sase Public Api](https://docs.nebulock.io/reference/get_rule_run_results_scheduled_sase_public_api_public_v1_rules__rule_id__runs__rule_run_id__get.md): Get row-level results for a single scheduled-sase run.