Home

Custom OpenSearch and OpenSearch Dashboards to support agentic pentest research. Stand up a local instance, point tools at it, then use the structured data for manual, automated, or agentic analysis. The code repository holds Compose and start scripts. These pull the matching runtime images from Docker Hub.

Prerequisites

• Docker with Compose V2 (docker compose version). Install from Docker’s docs rather than distribution-default packages when possible:
  • Docker Desktop (Windows, macOS, and Linux) — includes Compose
  • Docker Engine (Linux) — follow the guide for your distribution; see also Install Docker Compose
• Git, to obtain and update the code repository.

Quick Start

Clone and Configure Environment

git clone https://github.com/AnomalousVectors/opensearch.git
cd opensearch
cp .env.example .env

Example hostnames such as opensearch.url appear in some commands and configs. Replace them with IPs or resolvable names.

Edit .env using the comments in .env.example as a guide:

• Set DATA_VOLUME_ROOT to a persistent path outside the repository (indexes, logs, TLS material)
• Adjust OPENSEARCH_JAVA_OPTS (-Xms / -Xmx) if needed. The defaults in .env.example are usually fine on most systems; raise heap for heavy ingest, large documents, or demanding Discover use, and leave enough host RAM outside the JVM for the OS page cache.

Start

Linux / macOS:

chmod +x scripts/*.sh
./scripts/start.sh

Windows:

.\scripts\start.ps1

Behavior of the start script:

1. First run (no OpenSearch data yet under ${DATA_VOLUME_ROOT}/data):
   • Prompts for an initial admin password (with confirmation) and reminds you to save it
   • Starts OpenSearch (TLS certificates generate under ${DATA_VOLUME_ROOT}/certs if needed)
   • Validates the password against OpenSearch, then starts Dashboards
2. Subsequent runs (data already present):
   • Starts OpenSearch
   • Prompts again for the same admin password, validates it, then starts Dashboards
   • That typed password is used only for this run so Dashboards can talk to OpenSearch; it is not persisted on disk

Self-signed certificates are automatically generated for convenience. To use your own, see TLS certificates.

Stop, Destroy, and Health

Linux / macOS:

./scripts/stop.sh
./scripts/destroy.sh
./scripts/health.sh

Windows:

.\scripts\stop.ps1
.\scripts\destroy.ps1
.\scripts\health.ps1

stop and destroy remove Compose containers and the associated network (destroy runs compose down --remove-orphans). Neither removes files under DATA_VOLUME_ROOT. Delete that directory only when you intend a full reset.

Compose from the repository root remains available, for example docker compose -f compose.yml ps or docker compose -f compose.yml logs -f.

After the stack is healthy, point ingest tools at the OpenSearch API (OpenSearch). That page also covers post-import API checks (counts, search, refresh), cross-platform curl usage, single-node yellow status, and large document fields. Reviewing indexed data in the UI is covered under OpenSearch Dashboards.

Admin password

OpenSearch stores only a hash of the admin password in its security index under DATA_VOLUME_ROOT. Keep the plaintext yourself; the start script does not save it. Use the same admin credential for the Dashboards login UI and for API clients.

On every start after the first, the script asks for that password again so Dashboards can connect to OpenSearch for that run. Browser and API logins use the same saved credential.

Recovery and rotation are your responsibility. If the current password is known, see OpenSearch's Change Password API. For broader Security plugin recovery, begin with OpenSearch's documentation on applying security configuration.

TLS certificates

On first start, if ${DATA_VOLUME_ROOT}/certs is missing required files, the stack generates a local self-signed CA and server certificates there. Generated OpenSearch leaf files are named opensearch.pem / opensearch-key.pem (CN=opensearch, with SANs for localhost, opensearch, and opensearch.url). Dashboards leaves use dashboards.pem / dashboards-key.pem. root-ca.srl may appear as an OpenSSL serial artifact; clients do not need it.

Use your own certificates

Prefer placing your files in ${DATA_VOLUME_ROOT}/certs before the first start.

If the stack has already generated certificates, replace those files and restart the stack (scripts/start.sh or .\scripts\start.ps1, or an equivalent compose down/up). OpenSearch and Dashboards do not reload new PEM files while running.

This stack expects:

File	Role
root-ca.pem	CA certificate (trusted by OpenSearch and Dashboards)
opensearch.pem	OpenSearch HTTP/transport certificate
opensearch-key.pem	OpenSearch private key
dashboards.pem	OpenSearch Dashboards certificate
dashboards-key.pem	OpenSearch Dashboards private key

Leaf certificates should match what the stack uses for identity (OpenSearch leaf CN=opensearch with SANs covering how you reach the API; Dashboards leaf CN=opensearch-dashboards). Clients that verify TLS must trust root-ca.pem (or use an insecure trust mode deliberately).

Optional: root-ca-key.pem if you want the stack tooling able to mint additional leaf certificates from that CA.

The entrypoint creates only missing files, so a complete custom set in that directory is left as-is.

Private keys (*-key.pem) are restricted on start: mode 600 (and the certs directory 700) on Linux/macOS host mounts; on Windows, NTFS ACLs allow only the current user and Administrators. Public certificates are not world-shared via a loose certs directory ACL. Keep DATA_VOLUME_ROOT on a path other local users cannot read.

URLs

From the host, use:

• OpenSearch API: https://127.0.0.1:9200 (or your published port)
• Dashboards UI: https://127.0.0.1:5601 (accept the self-signed certificate warning)

Inside Compose, OpenSearch is also reachable as https://opensearch.url:9200 (service alias). See the note at the top of this page about example hostnames.

Upgrading images

cd opensearch
git pull
scripts/start.sh # or .\scripts\start.ps1 on Windows

Your data under DATA_VOLUME_ROOT is left in place.

Contributing and license

Issues and pull requests are welcome on the code repository. The project is licensed under the MIT License.