Security setup

OpenSearch Doctor's agent only needs read access to cluster metadata APIs. It never reads your indexed documents. This page shows you how to create a minimal-permission OpenSearch user for the agent — so you can verify exactly what it can and cannot access.

APIs used by the agent

The agent calls only these OpenSearch endpoints:

None of these endpoints return document content. They return cluster and index metadata only.

Create a minimal-permission role for the agent

We recommend creating a dedicated OpenSearch user with only the permissions the agent needs. This way you can verify — and enforce — that the agent cannot read your data.

Step 1 — Create the role

Run this against your OpenSearch cluster:

PUT /_plugins/_security/api/roles/opensearch_doctor_agent
{
  "cluster_permissions": [
    "cluster:monitor/health",
    "cluster:monitor/stats",
    "cluster:monitor/nodes/info",
    "cluster:monitor/nodes/stats",
    "cluster:monitor/nodes/usage",
    "cluster:monitor/state",
    "cluster:monitor/settings/get",
    "cluster:monitor/task/get",
    "cluster:monitor/tasks/lists"
  ],
  "index_permissions": [
    {
      "index_patterns": ["*"],
      "allowed_actions": [
        "indices:monitor/stats",
        "indices:monitor/recovery",
        "indices:monitor/settings/get",
        "indices:monitor/shards/search_shards"
      ]
    }
  ]
}

This role grants cluster:monitor/* and indices:monitor/* only. It explicitly does not include indices:data/read/*, which is required to read document content. An agent using this role cannot execute _search or read any indexed document.

Step 2 — Create the user

PUT /_plugins/_security/api/internalusers/opensearch_doctor_agent
{
  "password": "your-strong-password-here",
  "backend_roles": [],
  "attributes": {}
}

Step 3 — Map the user to the role

PUT /_plugins/_security/api/rolesmapping/opensearch_doctor_agent
{
  "users": ["opensearch_doctor_agent"]
}

Step 4 — Configure the agent

In your agent configuration file (agent.yaml), set the credentials for the restricted user:

opensearch:
  endpoint: "https://localhost:9200"
  username: "opensearch_doctor_agent"
  password: "your-strong-password-here"
  tls_skip_verify: false

Verify the restriction works

You can confirm the agent user cannot read your data by running a search request with its credentials — you should receive a 403 Forbidden:

curl -u opensearch_doctor_agent:your-password \
  "https://localhost:9200/your-index/_search" \
  -k

# Expected response:
# {"error":{"type":"security_exception","reason":"no permissions for [indices:data/read/search]"},"status":403}

If you see a 403, the restriction is working correctly. The agent cannot read your indexed data.

Using the admin user (simpler setup)

If you prefer a simpler setup and trust the platform, you can use your admin credentials directly. The agent only calls the metadata APIs listed above regardless of what permissions it has — but the minimal-permission approach gives you cryptographic proof of that.

The choice is yours. Both setups work identically from a diagnostics perspective.

No OpenSearch Security plugin?

If you're running a minimal OpenSearch setup without the Security plugin (common in dev/staging), there are no credentials to configure. Leave the username and passwordfields empty in agent.yaml.