# Docs

- Usage: Setup, workflows, and day-to-day detection engineering
  - [Usage](/docs/usage): Install opentide, learn the object model, and run detection-as-code — a guided path for detection engineers, agents, and integrators.
  - [Why opentide](/docs/usage/why-opentide): The problem detection-as-code teams hit at scale, and the design goals that shape opentide.
  - [How opentide works](/docs/usage/how-it-works): The end-to-end DetectionOps lifecycle — from authoring objects to deploying and documenting detections in CI.

  - **Concepts**
  - [Object model](/docs/usage/concepts/object-model): Threat vectors, detection objectives, and MDR rules — what each is for, how they chain, and how to author them.
  - [Platforms](/docs/usage/concepts/platforms): Eight deployment platforms, six query validators, and where each platform block schema is specified.
  - [Schema revision](/docs/usage/concepts/schema-revision): Why every object has two version fields, what each one controls, and how schema revisions coexist.
  - [Deployment state](/docs/usage/concepts/deployment-state): Where opentide keeps the vendor rule ids that Defender for Endpoint, SentinelOne and CrowdStrike assign, and why the files must be committed.
  - [Glossary](/docs/usage/concepts/glossary): Definitions for the opentide terms and acronyms used throughout the docs.
  - [Choosing an interface](/docs/usage/choosing-an-interface): When to use the CLI, the Python SDK, or the MCP server — they are three doors to the same engine.

  - **Get started**
  - [Installation](/docs/usage/installation): Install opentide from PyPI — one package, CLI, MCP, and all platforms.
  - [Repository setup](/docs/usage/repository-setup): How opentide setup scaffolds detection repositories, CI, MCP, and agent skills.
  - [Quickstart](/docs/usage/quickstart): Validate, generate schemas, and inspect a detection repository in five minutes.
  - [Tutorial: your first detection](/docs/usage/tutorial): Build a complete threat → objective → rule chain, validate it, fix an error, and dry-run a deploy — end to end.
  - [Configuration](/docs/usage/configuration): What lives in .opentide/configurations/ — enabling platforms, credentials, deployment statuses, promotion, and visibility.

  - **Workflows**
  - [Detection-as-code](/docs/usage/workflows/detection-as-code): The day-to-day loop for authoring, reviewing, promoting, and deploying detection objects.
  - [CI/CD](/docs/usage/workflows/ci-cd): Gate detection content on every PR and deploy on merge — GitHub, GitLab, and Azure pipelines with staging, promotion, and secrets.
  - [Agentic setup](/docs/usage/workflows/agentic-setup): Configure MCP servers and agent skills so AI assistants work safely with detection content — with an example session and its limits.

  - **Operate**
  - [Troubleshooting](/docs/usage/troubleshooting): Common opentide failures — validation errors, generation drift, platform loading, and deployment — with fixes.

  - **Migration**
  - Migration
    - [Migration guide](/docs/usage/migration): Upgrade detection repositories from CoreTide git submodules to the opentide PyPI package.
    - [CoreTide migration prompt](/docs/usage/migration/prompt): Copy-paste LLM prompt for migrating legacy CoreTide submodule repositories to opentide.
- Specifications: Normative opentide specifications for authors, maintainers, and agents
  - [Specifications](/docs/specifications): What a Tide object is, how the object families chain, and how to read the normative opentide specifications.
  - [opentide spec index](/docs/specifications/SPECS): One-page index of active normative spec versions — each spec is independently versioned.
  - [Conformance](/docs/specifications/conformance): How to read the normative keywords (MUST, SHOULD, MAY) used throughout the opentide specifications.

  - **Core**
  - [Versioning](/docs/specifications/specs/versioning): `metadata.schema` says which shape an object has. `metadata.version` says how that object's content has changed. They are not interchangeable.
  - [Metadata](/docs/specifications/specs/metadata): Shared metadata block present on all Tide objects (threat, objective, rule). Provides identity, schema routing, versioning, provenance, and classification.
  - [Workspace layout](/docs/specifications/specs/workspace): Defines the standard detection-repository directory layout scaffolded by `opentide setup` and used for object storage, generated artifacts, documentation mirrors, and client configuration overrides.
  - [Configuration and overrides](/docs/specifications/specs/configuration): opentide merges bundled package configuration with optional client overrides from `.opentide/configurations/`. Deep merge applies at the TOML key level; later layers override earlier ones for scalar and replaced subtrees.
  - [Deployment lifecycle](/docs/specifications/specs/deployment): Defines rule deployment statuses, promotion strategy, proxy settings, and debug configuration. Shipped in bundled `deployment.toml`; clients MAY override via `.opentide/configurations/deployment.toml`.
  - [Deployment state](/docs/specifications/specs/deployment-state): Microsoft Defender for Endpoint, SentinelOne, and CrowdStrike give every rule opentide creates an id of their own. The next deploy has to update, disable, or delete the remote rule by that id, and the id is per tenant. opentide keeps it in one committed JSON file per rule, `.opentide/states/deployment/<uuid>.json` (`de
  - [Validation](/docs/specifications/specs/validation): opentide validates detection content through a structured pipeline: ID uniqueness, UUID format, Pydantic schema validation, vocabulary conformance, deprecated field warnings, and cross-object reference checks. Optional checks include CVE scanning and per-platform query validation.
  - [Metaschema keywords](/docs/specifications/specs/metaschema-keywords): opentide extends JSON Schema generation with `tide.*` keywords in its metaschema. At generation time the implementation walks the metaschema depth-first and resolves each keyword into standard JSON Schema constructs; the `tide.*` keywords are then stripped from the emitted client-facing schemas.

  - **Platforms**
  - Platforms
    - [Platforms](/docs/specifications/specs/platforms): opentide ships eight detection platform integrations. Each platform has bundled TOML configuration, a deployer, an optional query validator, and a typed rule block under `configurations.<platform>`.
  - [Microsoft Sentinel (`platform::sentinel::1.0`)](/docs/specifications/specs/platforms/sentinel-1.0): `configurations.sentinel` is a Microsoft Sentinel scheduled analytics rule, or a near-real-time (NRT) rule when `scheduling.nrt` is true. The detection text is KQL. Query validation is supported. The analytics rule id sent to Sentinel is the rule's `metadata.uuid`.
  - [Microsoft Defender for Endpoint (`platform::defender_for_endpoint::1.0`)](/docs/specifications/specs/platforms/defender-for-endpoint-1.0): `configurations.defender_for_endpoint` is a Microsoft Defender custom detection rule. The detection text is KQL. Query validation is supported. Defender assigns the remote rule id; opentide stores it per tenant in [deployment state](/docs/specifications/specs/deployment-state/) so the next deploy updates that rule.
  - [Splunk (`platform::splunk::1.0`)](/docs/specifications/specs/platforms/splunk-1.0): `configurations.splunk` is a Splunk saved search. The detection text is SPL. Query validation is supported. Enterprise Security notable events, risk, and correlation search are optional blocks on top of the saved search.
  - [SentinelOne (`platform::sentinel_one::1.0`)](/docs/specifications/specs/platforms/sentinel-one-1.0): `configurations.sentinel_one` is a SentinelOne STAR rule. The detection text is S1QL, either one query (`Single Event`) or an ordered set of queries (`Correlation`). Query validation is supported. SentinelOne assigns the remote rule id; opentide stores it per tenant in [deployment state](/docs/specifications/specs/deployment-state/).
  - [VMware Carbon Black Cloud (`platform::carbon_black_cloud::1.0`)](/docs/specifications/specs/platforms/carbon-black-cloud-1.0): `configurations.carbon_black_cloud` is a Carbon Black Cloud Enterprise EDR watchlist report. The detection text is a Lucene query stored as an IOC. Query validation is supported. The IOC id is the Tide rule's `metadata.uuid`. The report is matched by title inside a watchlist that must already exist on the console.
  - [CrowdStrike Falcon (`platform::crowdstrike::1.0`)](/docs/specifications/specs/platforms/crowdstrike-1.0): `configurations.crowdstrike` is a CrowdStrike Falcon correlation rule. The detection text is the correlation filter. There is no query validator: `opentide validate query --platform crowdstrike` reports unsupported. CrowdStrike assigns the remote rule id; opentide stores it per tenant in [deployment state](../deploymen
  - [HarfangLab (`platform::harfanglab::1.0`)](/docs/specifications/specs/platforms/harfanglab-1.0): `configurations.harfanglab` is a HarfangLab detection rule, either a Sigma behavioural rule or a YARA scan rule. There is no query validator. The HarfangLab rule id is the Tide rule's `metadata.uuid` for both kinds. A block may carry both `sigma` and `yara`; deploy publishes the Sigma rule and does not publish the YARA
  - [Elastic Security (`platform::elastic::1.0`)](/docs/specifications/specs/platforms/elastic-1.0): `configurations.elastic` is an Elastic Security detection rule. Deploy creates it through the Kibana detection engine API (`/api/detection_engine/rules`, API version `2023-10-31`). One platform serves self-managed, Elastic Cloud Hosted, and Elastic Cloud Serverless Security: the deployment type changes only the tenant

  - **Objects**
  - [Threat vector (TVM)](/docs/specifications/specs/objects/threat-1.0): A threat vector describes an adversary capability or scenario: severity, impact, ATT&CK mapping, and optional chaining relationships. Schema identifier: `threat::1.0`.
  - [Detection objective (DOM)](/docs/specifications/specs/objects/objective-1.0): A detection objective defines what to detect: prioritized signals, composition strategy, and links to threat vectors. Schema identifier: `objective::1.0`.
  - [Detection rule (MDR)](/docs/specifications/specs/objects/rule-1.0): A detection rule (MDR — Managed Detection Rule) is the deployable unit of detection content: metadata, severity, ATT&CK techniques, platform-specific query configurations, optional response playbook, and lifecycle status. Schema identifier: `rule::1.0`.

  - **Vocabularies**
  - [Vocabulary format](/docs/specifications/specs/vocabularies/format): opentide vocabularies are TOML files (`.vocab.toml`) defining allowed enum values for object and configuration fields. Canonical copies live in `vocabularies/`; opentide bundles them at build time.
  - [Vocabulary catalog](/docs/specifications/specs/vocabularies/catalog): Index of canonical vocabulary files bundled with opentide. Each file lives in `vocabularies/` and is referenced by field path in object specs and metaschema `tide.vocab` keywords.

  - **Governance**
  - [Governance](/docs/specifications/GOVERNANCE): How opentide specifications are proposed, reviewed, versioned, and published — and why the model is shaped this way.

  - **RFCs**
  - RFCs: Proposals for changes to the opentide specifications
    - [RFC index](/docs/specifications/rfcs): Request for Comments (RFCs) document significant specification changes before they land in specs/.

    - **Proposed**
    - [RFC 0003: Per-key vocabulary versioning and schema pins](/docs/specifications/rfcs/0003-per-key-vocabulary-versioning): This RFC replaces file-level vocabulary versioning with per-key lifecycle metadata on each [[keys]] entry.
    - [RFC 0002: Vocabulary identifier versioning and schema pins](/docs/specifications/rfcs/0002-vocabulary-versioning): This RFC introduces versioned vocabulary identifiers in the form field::major.minor, adds schema-level vocabulary pinning through tide.vocab, and defines bump rules when…

    - **Draft**
    - [RFC 0012: Rules should read like the other objects](/docs/specifications/rfcs/0012-rule-document-shape): A threat file has a threat: block. An objective file has an objective: block.
    - [RFC 0011: Signal reuse across detection objectives](/docs/specifications/rfcs/0011-signal-reuse): A detection objective (DOM) may incorporate a signal defined on another objective that is already in the repository.
    - [RFC](/docs/specifications/rfcs/0009-machine-readable-vocabulary-contract): This repository is the normative source for opentide's taxonomy, but it publishes that taxonomy as documents for people rather than as a contract for machines.
    - [RFC 0008: Optional review date on detection rules](/docs/specifications/rfcs/0008-rule-reviewed-date): Add an optional metadata.reviewed timestamp so a consumer can list detection rules (MDR) that have no recorded review, or whose last review is older than a chosen window.
    - [RFC](/docs/specifications/rfcs/0005-scoped-signal-entities): objective.signals[].entities becomes stage-scoped: an authored value is <stage>::<key>, as threat.surface already is.

    - **Accepted**
    - [RFC 0010: Deployment external ids](/docs/specifications/rfcs/0010-deployment-external-ids): Vendor-assigned rule ids leave the rule file and move to .opentide/states/deployment/<metadata.uuid>.json (deployment.state::1.0).
    - [RFC 0007: Elastic Security detection platform](/docs/specifications/rfcs/0007-elastic-security-platform): Add a detection platform, elastic (display name Elastic Security, schema platform::elastic::1.0), that deploys opentide rules as Elastic SIEM detection rules.
    - [RFC 0006: Sharing on the production merge](/docs/specifications/rfcs/0006-sharing-ci): opentide setup and opentide setup ci gain an optional sharing stage, default off.
    - [RFC 0005: Sharing system and MISP connector](/docs/specifications/rfcs/0005-sharing-system): Add a first-class sharing subsystem to opentide: pluggable connectors, one workspace file sharing.toml in which every destination is a block under its integration…
    - [RFC 0001: Authority model and change process](/docs/specifications/rfcs/0001-authority-model): This RFC establishes the normative authority chain for opentide: markdown specs in the specifications repository are canonical; opentide Pydantic models implement them; JSON…

    - **Template**
    - [RFC template](/docs/specifications/rfcs/0000-template): Starting point for a new proposal. Not a live RFC.
- CLI: Technical command-line reference
  - [CLI reference](/docs/cli): Complete opentide command-line interface — commands, flags, exit codes, and JSON output.

  - **Global**
  - [Global options](/docs/cli/global-options): Repository root, data root, debug logging, colour, JSON output, and version flags shared by all CLI commands.
  - [Exit codes](/docs/cli/exit-codes): What each opentide exit code means, and how to gate CI on them.

  - **Commands**
  - [opentide setup](/docs/cli/setup): Repository scaffolding, platform configs, CI pipelines, env files, Git hooks, MCP, agent skills, and VS Code helpers.
  - [opentide migrate](/docs/cli/migrate): Move legacy Configurations/, Objects/, and .opentide/framework paths into the greenfield layout.
  - [opentide generate](/docs/cli/generate): Output-first generation pipeline — docs, exports, vocabs, templates, schemas, snippets, and optional platform import.
  - [opentide validate](/docs/cli/validate): Object validation (schema, UUID, uniqueness) and platform query syntax validation.
  - [opentide lint](/docs/cli/lint): Catalogue hygiene — filename slugs and recommended metadata, distinct from schema validation.
  - [opentide rules](/docs/cli/rules): Detection rule maintenance — list rules with no review date, or a review older than a window.
  - [opentide deploy](/docs/cli/deploy): Deploy the changed rules whose status maps to a strategy, to the tenants that accept it.
  - [opentide share](/docs/cli/share): Publish Tide objects to a MISP destination as one Event per object.
  - [opentide info](/docs/cli/info): Repository statistics, platform capabilities, object listings, and ATT&CK coverage lookup.
- MCP: Model Context Protocol server for detection engineering agents
  - [MCP server](/docs/mcp): opentide MCP server — search, validate, deploy, and query detection content from AI agents and editors.
  - [MCP installation](/docs/mcp/installation): Install opentide and start the stdio server with opentide mcp start.
  - [MCP configuration](/docs/mcp/configuration): Editor MCP config files, environment variables, and multi-host setup with opentide setup mcp.

  - **Reference**
  - [MCP tools](/docs/mcp/tools): Tool reference for the opentide MCP server — parameters, behaviour, and response shapes.
  - [MCP resources](/docs/mcp/resources): opentide:// resource URIs for catalogue indexes, objects, schemas, templates, and vocabularies.
- SDK: Python package API for embedding opentide
  - [Python SDK](/docs/sdk): Embed opentide in Python applications — registry lifecycle, validation, documentation, and platform plugins.
  - [SDK installation](/docs/sdk/installation): Install opentide as a library dependency with PEP 561 typing support.

  - **Core**
  - [Registry API](/docs/sdk/registry): opentide registry lifecycle, typed object access, configuration accessors, and lookup.
  - [Validation API](/docs/sdk/validation): Programmatic validation with ValidationScope, ValidateCheck, and ValidationReport.
  - [Documentation API](/docs/sdk/documentation): Render and publish markdown documentation for rules, objectives, and threats.

  - **Models**
  - [Models](/docs/sdk/models): Pydantic models for rules, objectives, and threats — key fields, delegation methods, results, and errors.
  - [Platforms API](/docs/sdk/platforms): Platform registry, entry-point plugins, deployers, and query validators.