diff --git a/deployments/helm/openhound/README.md b/deployments/helm/openhound/README.md index 15df3a8..cda77dc 100644 --- a/deployments/helm/openhound/README.md +++ b/deployments/helm/openhound/README.md @@ -26,7 +26,7 @@ helm install -f values.yml openhound- ./deployments/helm/openhound # Example values for the JAMF collector image: repository: docker.io/specterops/openhound - tag: "0.1.0-enterprise" + tag: "0.1.1-enterprise" # Optional environment variables. env: diff --git a/deployments/helm/values.example.yaml b/deployments/helm/values.example.yaml index 5a0bdc9..2966be0 100644 --- a/deployments/helm/values.example.yaml +++ b/deployments/helm/values.example.yaml @@ -1,7 +1,7 @@ # Example values for the JAMF collector image: repository: docker.io/specterops/openhound - tag: "0.1.0-enterprise" + tag: "0.1.1-enterprise" # Optional environment variables. env: diff --git a/docker-compose.yml b/docker-compose.yml deleted file mode 100644 index c9d5a1c..0000000 --- a/docker-compose.yml +++ /dev/null @@ -1,63 +0,0 @@ -# This is an example docker-compose file for running OpenHound with the JAMF collector. -# the output graph will be stored inside a named volume. You can copy the OpenGraph contents using the -# following command: ` cp :/tmp/output/graph ` - -x-cli: &cli - image: specterops/openhound:latest - restart: no - volumes: - - ${HOME}/.dlt/config.toml:/app/.dlt/config.toml:ro - - jamf-output:/tmp/output - - # These environment variables can also be set inside the ~/.dlt/config.toml file - # and act as an example. Configuring openhound can be done using environment variables, - # configuration files or a combination of both. - environment: &env - LOG_LEVEL: INFO - EXTRACT__WORKERS: 8 - LOG_CONTAINER: true - - secrets: - - source: secrets_jamf - target: /app/.dlt/secrets.toml - -services: - collect-jamf: - <<: *cli - command: - - collect - - jamf - - /tmp/output/raw - - --progress=log - - preprocess-jamf: - <<: *cli - command: - - preprocess - - jamf - - /tmp/output/raw/jamf - - /tmp/output/lookup.duckdb - - --progress=log - depends_on: - collect-jamf: - condition: service_completed_successfully - - convert-jamf: - <<: *cli - command: - - convert - - jamf - - /tmp/output/raw/jamf - - /tmp/output/graph - - --lookup-file=/tmp/output/lookup.duckdb - - --progress=log - depends_on: - preprocess-jamf: - condition: service_completed_successfully - -volumes: - jamf-output: - -secrets: - secrets_jamf: - file: ${HOME}/.dlt/secrets_jamf.toml diff --git a/example-configurations/bloodhound-community/.dlt-example/config.toml b/example-configurations/bloodhound-community/.dlt-example/config.toml new file mode 100644 index 0000000..8122887 --- /dev/null +++ b/example-configurations/bloodhound-community/.dlt-example/config.toml @@ -0,0 +1,16 @@ +# Example configuration: https://bloodhound.specterops.io/openhound/configuration +[runtime] +http_show_error_body = true +log_cli_level = "WARNING" +log_format = "JSON" +log_rotate_when = "midnight" + +[extract] +workers = 8 + +[normalize] +workers = 3 + +[load] +delete_completed_jobs = true +truncate_staging_dataset = true diff --git a/example-configurations/bloodhound-community/.dlt-example/secrets_github.toml b/example-configurations/bloodhound-community/.dlt-example/secrets_github.toml new file mode 100644 index 0000000..5d34e7d --- /dev/null +++ b/example-configurations/bloodhound-community/.dlt-example/secrets_github.toml @@ -0,0 +1,6 @@ +# Example configuration for github secrets: https://bloodhound.specterops.io/openhound/collectors/github/collect-data#example-configuration +[sources.source.github.credentials] +app_id = "myappid" +client_id = "myclientid" +key_path = "/app/.dlt/github.pem" +org_name = "myorgname" diff --git a/example-configurations/bloodhound-community/.dlt-example/secrets_jamf.toml b/example-configurations/bloodhound-community/.dlt-example/secrets_jamf.toml new file mode 100644 index 0000000..8908dbf --- /dev/null +++ b/example-configurations/bloodhound-community/.dlt-example/secrets_jamf.toml @@ -0,0 +1,5 @@ +# Example configuration for jamf secrets: https://bloodhound.specterops.io/openhound/collectors/jamf/collect-data#example-configuration +[sources.source.jamf] +username = "myusername" +host = "https://tenant.jamfcloud.com" +password = "mypassword" diff --git a/example-configurations/bloodhound-community/.dlt-example/secrets_okta.toml b/example-configurations/bloodhound-community/.dlt-example/secrets_okta.toml new file mode 100644 index 0000000..1dede40 --- /dev/null +++ b/example-configurations/bloodhound-community/.dlt-example/secrets_okta.toml @@ -0,0 +1,5 @@ +# Example configuration for okta secrets: https://bloodhound.specterops.io/openhound/collectors/okta/collect-data#example-configuration +[sources.source.okta.credentials] +base_url = "https://mytenant.oktapreview.com" +client_id = "myclientid" +private_key_path = "/app/.dlt/okta.json" diff --git a/example-configurations/bloodhound-community/README.md b/example-configurations/bloodhound-community/README.md new file mode 100644 index 0000000..30edfef --- /dev/null +++ b/example-configurations/bloodhound-community/README.md @@ -0,0 +1,17 @@ +## Quick-start + + 1. Copy the contents from `bloodhound-community` folder to `${HOME}`. + 2. Rename `.dlt-example` to `.dlt` and fill in your credentials in the toml files. + 3. Place any required key files (github.pem, okta.json) in `${HOME}/.dlt`. + 4. Pull image from SpecterOps Docker Hub: `docker pull specterops/openhound:latest` + or run to pull from docker-compose.yml: `docker compose pull` + 5. Run all collectors: `docker compose up -d` + or run a single one: `docker compose up -d collect-jamf preprocess-jamf convert-jamf` + + Example docker-compose file for running OpenHound with Jamf, GitHub, and Okta collectors. + Collector output is written to local bind-mount directories under `./output//`. + +## WARNING: + All config and secret files referenced below MUST exist before running + `docker compose up`. If they are missing, Docker will create them as directories, + which will cause the collector to fail. \ No newline at end of file diff --git a/example-configurations/bloodhound-community/docker-compose.yml b/example-configurations/bloodhound-community/docker-compose.yml new file mode 100644 index 0000000..2bc6e7e --- /dev/null +++ b/example-configurations/bloodhound-community/docker-compose.yml @@ -0,0 +1,162 @@ +x-cli: &cli + image: specterops/openhound:latest + restart: no + + # These environment variables can also be set inside the ~/.dlt/config.toml file + # and act as an example. Configuring openhound can be done using environment variables, + # configuration files or a combination of both. + environment: &env + LOG_LEVEL: INFO + EXTRACT__WORKERS: 8 + LOG_CONTAINER: true + +x-jamf: &jamf + <<: *cli + volumes: + - ${HOME}/.dlt/config.toml:/app/.dlt/config.toml:ro + - ./output/jamf:/tmp/output + secrets: + - source: secrets_jamf + target: /app/.dlt/secrets.toml + +x-github: &github + <<: *cli + volumes: + - ${HOME}/.dlt/config.toml:/app/.dlt/config.toml:ro + - ./output/github:/tmp/output + secrets: + - source: secrets_github + target: /app/.dlt/secrets.toml + - source: key_github + target: /app/.dlt/github.pem + +x-okta: &okta + <<: *cli + volumes: + - ${HOME}/.dlt/config.toml:/app/.dlt/config.toml:ro + - ./output/okta:/tmp/output + secrets: + - source: secrets_okta + target: /app/.dlt/secrets.toml + - source: key_okta + target: /app/.dlt/okta.json + +services: + # --- Jamf --- + collect-jamf: + <<: *jamf + command: + - collect + - jamf + - /tmp/output/raw + - --progress=log + + preprocess-jamf: + <<: *jamf + command: + - preprocess + - jamf + - /tmp/output/raw/jamf + - /tmp/output/lookup.duckdb + - --progress=log + depends_on: + collect-jamf: + condition: service_completed_successfully + + convert-jamf: + <<: *jamf + command: + - convert + - jamf + - /tmp/output/raw/jamf + - /tmp/output/graph + - --lookup-file=/tmp/output/lookup.duckdb + - --progress=log + depends_on: + preprocess-jamf: + condition: service_completed_successfully + + # --- GitHub --- + collect-github: + <<: *github + command: + - collect + - github + - /tmp/output/raw + - --progress=log + + preprocess-github: + <<: *github + command: + - preprocess + - github + - /tmp/output/raw/github + - /tmp/output/lookup.duckdb + - --progress=log + depends_on: + collect-github: + condition: service_completed_successfully + + convert-github: + <<: *github + command: + - convert + - github + - /tmp/output/raw/github + - /tmp/output/graph + - --lookup-file=/tmp/output/lookup.duckdb + - --progress=log + depends_on: + preprocess-github: + condition: service_completed_successfully + + # --- Okta --- + collect-okta: + <<: *okta + command: + - collect + - okta + - /tmp/output/raw + - --progress=log + + preprocess-okta: + <<: *okta + command: + - preprocess + - okta + - /tmp/output/raw/okta + - /tmp/output/lookup.duckdb + - --progress=log + depends_on: + collect-okta: + condition: service_completed_successfully + + convert-okta: + <<: *okta + command: + - convert + - okta + - /tmp/output/raw/okta + - /tmp/output/graph + - --lookup-file=/tmp/output/lookup.duckdb + - --progress=log + depends_on: + preprocess-okta: + condition: service_completed_successfully + +secrets: + # Jamf: username + password auth + secrets_jamf: + file: ${HOME}/.dlt/secrets_jamf.toml + + # GitHub: GitHub App auth (app_id, client_id, org_name) + private key PEM (github.pem) + secrets_github: + file: ${HOME}/.dlt/secrets_github.toml + key_github: + file: ${HOME}/.dlt/github.pem + + # Okta: OAuth client credentials (base_url, client_id) + private key JSON (okta.json) + secrets_okta: + file: ${HOME}/.dlt/secrets_okta.toml + key_okta: + file: ${HOME}/.dlt/okta.json diff --git a/example-configurations/bloodhound-enterprise/.dlt-example/config.toml b/example-configurations/bloodhound-enterprise/.dlt-example/config.toml new file mode 100644 index 0000000..119f7f9 --- /dev/null +++ b/example-configurations/bloodhound-enterprise/.dlt-example/config.toml @@ -0,0 +1,16 @@ +# Example configuration: https://bloodhound.specterops.io/openhound/enterprise#full-configuration-example +[runtime] +http_show_error_body = true +log_cli_level = "WARNING" +log_format = "JSON" +log_rotate_when = "midnight" + +[extract] +workers = 8 + +[normalize] +workers = 3 + +[load] +delete_completed_jobs = true +truncate_staging_dataset = true diff --git a/example-configurations/bloodhound-enterprise/.dlt-example/secrets_github.toml b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_github.toml new file mode 100644 index 0000000..45d062b --- /dev/null +++ b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_github.toml @@ -0,0 +1,13 @@ +# Example configuration for bhe secrets: https://bloodhound.specterops.io/openhound/enterprise#full-configuration-example +[destination.bloodhoundenterprise] +interval = "300" +token_key = "client_token_key" +token_id = "client_token_id" +url = "bhe_url" + +# Example configuration for github secrets: https://bloodhound.specterops.io/openhound/collectors/github/collect-data#example-configuration +[sources.source.github.credentials] +app_id = "myappid" +client_id = "myclientid" +key_path = "/app/.dlt/github.pem" +org_name = "myorgname" diff --git a/example-configurations/bloodhound-enterprise/.dlt-example/secrets_jamf.toml b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_jamf.toml new file mode 100644 index 0000000..c4aef0d --- /dev/null +++ b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_jamf.toml @@ -0,0 +1,12 @@ +# Example configuration for bhe secrets: https://bloodhound.specterops.io/openhound/enterprise#full-configuration-example +[destination.bloodhoundenterprise] +interval = "300" +token_key = "client_token_key" +token_id = "client_token_id" +url = "bhe_url" + +# Example configuration for jamf secrets: https://bloodhound.specterops.io/openhound/collectors/jamf/collect-data#example-configuration +[sources.source.jamf] +username = "myusername" +host = "https://mytenant.jamfcloud.com" +password = "mypassword" diff --git a/example-configurations/bloodhound-enterprise/.dlt-example/secrets_okta.toml b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_okta.toml new file mode 100644 index 0000000..cc667ea --- /dev/null +++ b/example-configurations/bloodhound-enterprise/.dlt-example/secrets_okta.toml @@ -0,0 +1,12 @@ +# Example configuration for bhe secrets: https://bloodhound.specterops.io/openhound/enterprise#full-configuration-example +[destination.bloodhoundenterprise] +interval = "300" +token_key = "client_token_key" +token_id = "client_token_id" +url = "bhe_url" + +# Example configuration for okta secrets: https://bloodhound.specterops.io/openhound/collectors/okta/collect-data#example-configuration +[sources.source.okta.credentials] +base_url = "https://mytenant.oktapreview.com" +client_id = "myclientid" +private_key_path = "/app/.dlt/okta.json" diff --git a/example-configurations/bloodhound-enterprise/README.md b/example-configurations/bloodhound-enterprise/README.md new file mode 100644 index 0000000..368f9a4 --- /dev/null +++ b/example-configurations/bloodhound-enterprise/README.md @@ -0,0 +1,16 @@ +## Quick-start + + 1. Copy the contents from `bloodhound-enterprise` folder to `${HOME}`. + 2. Rename `.dlt-example` to `.dlt` and fill in your credentials in the toml files. + 3. Place any required key files (github.pem, okta.json) in `${HOME}/.dlt`. + 4. Pull image from SpecterOps Docker Hub: `docker pull specterops/openhound:0.1.1-enterprise` + or run to pull from docker-compose.yml: `docker compose pull` + 5. Run all collectors: `docker compose up -d` + or run a single one: `docker compose up -d scheduler-jamf` + +Full configuration reference: https://bloodhound.specterops.io/openhound/enterprise + +## WARNING: + All config and secret files referenced below MUST exist before running + `docker compose up`. If they are missing, Docker will create them as directories, + which will cause the collector to fail. \ No newline at end of file diff --git a/docker-compose.bhe.yml b/example-configurations/bloodhound-enterprise/docker-compose.yml similarity index 73% rename from docker-compose.bhe.yml rename to example-configurations/bloodhound-enterprise/docker-compose.yml index ee3ad2d..b20b9cc 100644 --- a/docker-compose.bhe.yml +++ b/example-configurations/bloodhound-enterprise/docker-compose.yml @@ -1,5 +1,5 @@ x-scheduler: &scheduler - image: specterops/openhound:${IMAGE_VERSION:-0.1.0-enterprise} + image: specterops/openhound:${IMAGE_VERSION:-0.1.1-enterprise} restart: unless-stopped init: true volumes: @@ -14,6 +14,7 @@ x-scheduler: &scheduler LOG_CONTAINER: true services: + # --- Jamf --- scheduler-jamf: <<: *scheduler environment: @@ -23,6 +24,7 @@ services: - source: secrets_jamf target: /app/.dlt/secrets.toml + # --- GitHub --- scheduler-github: <<: *scheduler environment: @@ -34,6 +36,7 @@ services: - source: key_github target: /app/.dlt/github.pem + # --- Okta --- scheduler-okta: <<: *scheduler environment: @@ -46,12 +49,20 @@ services: target: /app/.dlt/okta.json secrets: + # Copy the .dlt-example folder to ${HOME}/.dlt as a starting point for each secrets file. + # Each secrets file must also contain [destination.bloodhoundenterprise] with url, token_id, and token_key. + + # Jamf: username + password auth secrets_jamf: file: ${HOME}/.dlt/secrets_jamf.toml + + # GitHub: GitHub App auth (app_id, client_id, org_name) + private key PEM (github.pem) secrets_github: file: ${HOME}/.dlt/secrets_github.toml key_github: file: ${HOME}/.dlt/github.pem + + # Okta: OAuth client credentials (base_url, client_id) + private key JSON (okta.json) secrets_okta: file: ${HOME}/.dlt/secrets_okta.toml key_okta: