> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/open-telemetry/hermes/security.md).

# Security

Hermes runs entirely in your own cloud and never phones home — read-only Salesforce access, JWT Bearer auth, TLS-only transport, configurable PII redaction.

Hermes's security posture starts with where it runs: **entirely inside your own cloud**, not Pharos's. Pharos never receives or stores the telemetry Hermes exports — there is no phone-home path. Salesforce is treated strictly as a **read-only telemetry and identity source**: Hermes reads Platform Events and `EventLogFile` records, and reads `AuthSession` for session enrichment, but no Hermes or Pharos product logic runs inside Salesforce itself. Everything Hermes does happens in the Docker image running in your infrastructure.

***

## Authentication

Hermes supports three ways to authenticate to Salesforce:

| Mode                                  | Credentials                                                                                                                                   | When to use                                                                                                                                                                                                        |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **JWT Bearer** (default, recommended) | External Client App consumer key + RSA private key + integration username, in `ORG_CONFIGS` (`sf.client_id`, `sf.private_key`, `sf.username`) | Every cloud deployment. No interactive login, no stored password; tokens are minted and refreshed automatically. The only mode `ORG_CONFIGS` carries.                                                              |
| **Username-password grant**           | `SF_PASSWORD` (+ optional `SF_SECURITY_TOKEN`) environment variables                                                                          | Single-org local runs where a keypair is not yet set up.                                                                                                                                                           |
| **Static access token**               | `SF_ACCESS_TOKEN` + `SF_INSTANCE_URL` environment variables                                                                                   | Local runs against a scratch org. The token is validated once at startup and then served verbatim — it is never refreshed, so a rejection after startup is terminal until the process restarts with a fresh token. |

The two environment-variable modes are **ignored, with a warning, whenever `ORG_CONFIGS` is set** — a multi-org deployment is always JWT Bearer. Whichever mode is in force, Salesforce's rejection of a credential is classified the same way and drives the `hermes_org_auth_failures_total` and `hermes_org_connected` [self-metrics](https://docs.pharos.ai/open-telemetry/configuration/self-metrics.md).

The External Client App's OAuth scopes are `Api`, `RefreshToken`, `OfflineAccess`, and `SFApiPlatform`. On the Salesforce side, access is granted through two read-only permission sets — one per component, each additive and independently sufficient for the component it covers. Both ship in the [pharos-permissions](https://resources.pharos.ai/pharos-permissions) download; assign them to the running user rather than assembling the permissions by hand.

| Permission set                            | Covers                                                               | User permissions                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Hermes_Iris`** (label "Hermes Iris")   | Iris — the subscription to the `pharos__Log_Event__e` platform event | `API Enabled`, `View All Platform Events`                                                                                                                                                                                                                                                                                                                        |
| **`Hermes_Argus`** (label "Hermes Argus") | Argus — Event Monitoring ingestion (RTEM and ELF)                    | `API Enabled`, `View All Platform Events`, `View Event Log Files`, `Event Log Read Access`, `View Threat Detection Events` (`ViewAnomalyEvents` and `ViewDataLeakageEvents`), `View All Data`, plus the permissions `View All Data` depends on: `View Public Dashboards`, `View Public Reports`, `View Roles and Role Hierarchy`, `View Setup and Configuration` |

`API Enabled` and `View All Platform Events` appear in both sets deliberately, so that either set on its own is enough for its own component. Nothing in either set lets Hermes write back into your org.

{% hint style="warning" %}
**A deployment running both components must assign both permission sets.** Assigning only `Hermes_Iris` while Argus is also running degrades session resolution silently: Iris keeps the session context the Apex trigger supplied, Argus resolves its own, and the two components' telemetry no longer groups into one trace. Nothing fails and nothing is dropped — the correlation simply stops happening.
{% endhint %}

The split exists because of `View All Data`, which grants read access to every record in the org. Only Argus needs it: Event Monitoring events carry no session context, so Argus reads `AuthSession` to anchor its spans to a session (see [Cross-Surface Correlation](https://docs.pharos.ai/open-telemetry/hermes/correlation.md#cross-channel-session-unification)). Iris receives the session in the log payload and needs nothing of the sort, so an Iris-only deployment never requires `View All Data` at all.

Where a customer's security policy bars `View All Data`, the `Hermes_Argus` set can use **`Manage Users`** instead — it also grants the `AuthSession` read Argus needs, over a much narrower slice of data. It is not strictly a reduction in privilege, though: `Manage Users` is write-capable, so it trades breadth of read access for the ability to modify users. Choose whichever your security policy treats as the lesser exposure.

{% hint style="info" %}
Setting up the External Client App correctly has a specific gotcha: "Issue JWT-based access tokens" must be left **disabled**, or the Pub/Sub API rejects the resulting token. See [Salesforce Setup](https://docs.pharos.ai/open-telemetry/configuration/salesforce-setup.md) for the full walkthrough.
{% endhint %}

***

## Transport

Export traffic from Hermes to your OTel backend is **OTLP over TLS by default**. If an endpoint is configured as plaintext and isn't on loopback, Hermes warns rather than silently sending telemetry unencrypted — you have to explicitly opt in to insecure transport (`insecure: true` on a `collector` or `otlp` block) if that's genuinely what you want, for example a Collector running as a separate service on a private network. A loopback sidecar on `127.0.0.1` needs no acknowledgement.

***

## PII Redaction

Redaction is **opt-in per org**. By default Hermes redacts nothing — enable it for every org whose compliance obligations require it.

* **Curated deny-list** (`hermes.redaction_enabled: true`). Iris and Argus both apply **11** named regex rules, in order, to every string attribute and log body they emit, regardless of which field they appear in: `password-reset-url`, `oauth-bearer-token`, `raw-jwt`, `access-token-param`, `login-key-surrogate`, `email-address`, `e164-phone`, `us-ssn`, `credit-card`, `authorization-basic`, `x-api-key-header`. The same flag activates the per-field `redact: true` rules that ship dormant in both default mappings.
* **Per-field overrides** (`hermes.redaction_overrides`). A list of emitted attribute keys, each with a strategy — `replace`, `drop`, `hash` (deterministic, correlatable), or `mask` (last four characters kept) — applied **whether or not** the curated set is enabled.
* **Allow-list mode** (`redaction_mode: allow-list` in the pipeline config). A deny-by-default posture: string and body values are dropped unless the attribute or log rule is explicitly allow-listed. Independent of the two controls above.

Full configuration detail — how the rules are structured, the recommended override starting point, and the Iris/Argus differences — lives in [Mapping & Redaction](https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md).

***

## Health Endpoints

Hermes exposes `/health`, `/ready`, `/stats`, and `/metrics` for operational monitoring. These endpoints are **unauthenticated by design** — they're meant to be cheap and simple for a container orchestrator or monitoring agent to poll. That means they must not be exposed publicly: keep them reachable only from inside your own network, the same way you would any other unauthenticated operational endpoint. The AWS and Azure Terraform modules give Hermes no public ingress.

***

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>☁️ Salesforce Setup</strong></td><td>Configure the External Client App, JWT auth, and read-only permissions</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/salesforce-setup.md">Salesforce Setup</a></td></tr><tr><td><strong>🗺️ Mapping &#x26; Redaction</strong></td><td>Deny-list defaults and per-field redaction strategies</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md">Mapping &amp; Redaction</a></td></tr><tr><td><strong>📡 Self-Instrumentation Metrics</strong></td><td>The connectivity and auth-failure metrics to alert on</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/self-metrics.md">Self-Instrumentation Metrics</a></td></tr></tbody></table>
