Skip to content

Configuration File

SFHound reads credentials and runtime settings from config.yaml in the sf-opengraph/ directory. All values can be overridden at the command line. See the CLI reference.

Quick start

cp config.yaml.example config.yaml
# Edit config.yaml with your values

Full schema

# ─── Salesforce connection ─────────────────────────────────────────────────────
salesforce:
  # Consumer Key from Connected App → Manage Consumer Details
  client_id: "YOUR_CONNECTED_APP_CONSUMER_KEY"

  # Optional: Consumer Secret (only required for client_credentials flow)
  # client_secret: "YOUR_CONSUMER_SECRET"

  # Salesforce username of the integration user
  username: "your.integration.user@example.com"

  # Path to your JWT private key (generated with openssl)
  private_key_path: "./salesforce_jwt.key"

  # Login URL
  # Production:   https://login.salesforce.com
  # Sandbox:      https://test.salesforce.com
  # My Domain:    https://yourorg.my.salesforce.com
  login_url: "https://login.salesforce.com"

  # Salesforce API version to target
  api_version: "v56.0"

# ─── BloodHound CE (optional — required for --auto-ingest) ────────────────────
bloodhound:
  # Base URL of your BloodHound CE instance
  url: "http://127.0.0.1:8080"

  # BloodHound admin credentials
  username: "admin"
  password: "YOUR_BLOODHOUND_PASSWORD"

  # Set to true to always upload after every run without passing --auto-ingest
  auto-ingest: false

# ─── Output ───────────────────────────────────────────────────────────────────
env:
  # Directory where the BloodHound-compatible JSON file is written
  output_path: "./opengraph_output"

Field reference

`salesforce` block

Key	Required	Type	Description
`client_id`	✅	string	Consumer Key from your Connected App’s “Manage Consumer Details” page
`client_secret`	❌	string	Consumer Secret — only needed for the `client_credentials` OAuth flow
`username`	✅	string	Salesforce username of the integration user (e.g. `sfhound@yourorg.com`)
`private_key_path`	✅	string	Relative or absolute path to the `salesforce_jwt.key` PEM file
`login_url`	✅	string	Salesforce login endpoint. Use `https://test.salesforce.com` for sandboxes
`api_version`	✅	string	Salesforce API version string in `vNN.N` format

`bloodhound` block

Key	Required	Type	Description
`url`	❌	string	BloodHound CE base URL. Required if using auto-ingest
`username`	❌	string	BloodHound CE admin username
`password`	❌	string	BloodHound CE admin password
`auto-ingest`	❌	boolean	If `true`, uploads to BloodHound after every run without `--auto-ingest` flag

`env` block

Key	Required	Type	Description
`output_path`	❌	string	Directory where the output JSON is written. Created if it does not exist

Examples

Sandbox org with manual upload

salesforce:
  client_id: "3MVG9..."
  username: "sfhound@myorg.sandbox"
  private_key_path: "./salesforce_jwt.key"
  login_url: "https://test.salesforce.com"
  api_version: "v56.0"

env:
  output_path: "./opengraph_output"

Production with auto-ingest enabled by default

salesforce:
  client_id: "3MVG9..."
  username: "sfhound@myorg.com"
  private_key_path: "/etc/sfhound/salesforce_jwt.key"
  login_url: "https://login.salesforce.com"
  api_version: "v60.0"

bloodhound:
  url: "http://bloodhound.internal:8080"
  username: "admin"
  password: "supersecret"
  auto-ingest: true

env:
  output_path: "/var/lib/sfhound/output"

Security notes

Store salesforce_jwt.key outside the repository (use an absolute path).
Use a secrets manager (Vault, AWS Secrets Manager) for CI/CD pipelines — pass credentials via environment variables rather than a checked-in config file.
Rotate the JWT certificate annually (or per your org’s key-rotation policy).

Validation

SFHound validates config.yaml at startup. Common errors:

Error	Cause
`Missing required field: salesforce.client_id`	`client_id` is absent or empty
`private_key_path not found: ./salesforce_jwt.key`	Key file does not exist at the specified path
`Invalid login_url`	URL does not start with `https://`
`api_version must match vNN.N`	Version string malformed (use `v56.0`, not `56.0` or `56`)