• Brimstone
  • Summary
  • Use Cases
    • Notable: Remediate Non-tracked Exposed Credential - Add Account
  • Usage
    • Brimstone Service Endpoints
  • Configuration
    • Brimstone Service
    • Hailstone App
    • Using an .env file
  • Walk Through
    • Setup
    • GG Incident Flow
    • HMSL Leak Flow
  • References
  • Technologies
  • Colophon
  • License
  • Contributing

Brimstone

Summary

Brimstone is a service that complements the GitGuardian (GG) service HasMySecretLeaked (HMSL). It takes in and stores the HMSL hashes to facilitate remediation actions such as rotating a password if one is found to be leaked.

Use Cases

#	Trigger	Data Source	Findings	Action	Use Case
1	Brimstone POST to HMSL	HMSL POST /v1/{prefixes,hashes} responses	No Matches	Do Nothing	If hash prefixes from Brimstone sent to HMSL return no matches, then this indicates no leaks of the PAM Accounts being tracked in Brimstone.
2	Brimstone POST to HMSL	HMSL POST /v1/{prefixes,hashes} responses	Matches Returned	For each "Matches" item, if it exists in Brimstone, then Change Account Password	If hash prefixes from Brimstone sent to HMSL return matches, then this indicates that the PAM Account secret is leaked.
3	GG Incident	GG Custom Webhook Incident	No Matches In Brimstone	Add Account in Pending Safe	GG tracks our own repos, so, if we find a secret in our codebase, immediately provision it.
4	GG Incident	GG Custom Webhook Incident	Matches In Brimstone	Change Account Password	GG tracks our own repos, so, if we find a secret in our codebase, and it matches an account in the PAM Vault rotate it.

Notable: Remediate Non-tracked Exposed Credential - Add Account

• When GitGuardian sends an incident to Brimstone, and there is no corresponding hmsl_hash, Brimstone will add an account to a pending safe. When looking in the pending safe, and
  • "Address" will contain the GitGuardian incident url
  • "Platform ID" will be "DummyPlatform"
  • "Username" and Account "Name" will be derived from the GG incident URL

Usage

Brimstone Service Endpoints

• API Key header

  Authorization: Bearer [[api key]]
  
  Example:
  Authorization: Bearer abcdef123456
  

• PUT /v1/hashes

  • Requires:

    • Content-type header, Content-type: application/json
    • Authorization Header, Authorization: Bearer [[api key]]

  • CPM plugin uses this endpoint to update hashes in Brimstone

  • Brimstone to accept payload, add new hashes and rotate hashes to Current-1, Current-2

  • Request body is HashBatch structure as serialized JSON

  • Example curl call:

    curl -X PUT \
    -H "Authorization: Bearer abcdef123456" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "http://127.0.0.1:9090/v1/hashes" \
    -d '{
      "hashes" : [ {
        "name" : "name1",
        "hash" : "hash1"
      }, {
        "name" : "name2",
        "hash" : "hash2"
      } ],
      "safename" : "safename1"
    }'

• GET /v1/hashes/sendprefixes

  • Requires Authorization Header, Authorization: Bearer [[api key]]
  • Trigger Brimstone to push current list of hashes as prefixes to HMSL

• GET /v1/hashes/sendhashes

  • Requires Authorization Header, Authorization: Bearer [[api key]]
  • Trigger Brimstone to push current list of full hashes to HMSL

• POST /v1/notify/ggevent

  • Brimstone will verify the incoming request per GG Custom Webhook Doc
  • Endpoint used to configure GG "custom webhook"

Configuration

Brimstone Service

Type	Name	Example Value	Required	Notes
Environment variable	BRIMSTONE_API_KEY	BRIMSTONE_API_KEY	N	default env var name is BRIMSTONE_API_KEY
Environment variable	HMSL_URL	https://api.hasmysecretleaked.com	N	HMSL url where to send hashes (Used as audience when sending JWT request), default value is https://api.hasmysecretleaked.com
Environment variable	HMSL_AUDIENCE_TYPE	hmsl	N	Audience type for HMSL JWT request, default value is hmsl
Environment variable	GG_API_URL	https://api.gitguardian.com	N	GG API URL, default is https://api.gitguardian.com
Environment variable	GG_API_TOKEN	GG_API_TOKEN_VARNAME	Y	GG API token can be retrieved from GG Dashboard -> API -> Personal access tokens (default env var name: GG_API_TOKEN)
Environment variable	GG_WEBHOOK_TOKEN	GG_WEBHOOK_TOKEN_VARNAME	Y	GG API Token env var contains GG API token to use (default env var name: GG_WEBHOOK_TOKEN)
Environment variable	DB_URL	postgresql://root@localhost:26257/brimstone?sslmode=disable&application_name=brimstone	N	Database URL, supports postgres:// adn sqlite://, default is postgresql://root@localhost:26257/brimstone?sslmode=disable&application_name=brimstone
Environment variable	PORT	9191	N	Port whereon Brimstone listens, default: 9191
Environment variable	ID_TENANT_URL	https://EXAMPLE.id.cyberark.cloud	Y	PAM config ID tenant URL
Environment variable	PCLOUD_URL	https://EXAMPLE.privilegecloud.cyberark.cloud	Y	PAM config Privilege Cloud URL
Environment variable	PAM_USER	pam user	Y	PAM config PAM User
Environment variable	PAM_PASS	pam user password	Y	PAM config PAM Pass
Environment variable	SAFE_NAME	Pending	Y	PAM config PAM Pending Safe Name. Note: safe must already exist and pamuser can add and change accounts.
Environment variable	PLATFORM_ID	UnixSSH	Y	Platform used when creating accounts
Parameter	-version		N	Print version and exit
Parameter	-d		N	Set output level to debug

Hailstone App

Type	Name	Example Value	Required	Notes
Parameter	-d		N	enable debug mode
Environment variable	ID_TENANT_URL	https://EXAMPLE.id.cyberark.cloud	Y	PAM config ID tenant URL
Environment variable	PCLOUD_URL	https://EXAMPLE.privilegecloud.cyberark.cloud	Y	PAM config Privilege Cloud URL
Environment variable	PAM_USER	pam user	Y	PAM config PAM User
Environment variable	PAM_PASS	pam user password	Y	PAM config PAM Pass
Environment variable	SAFE_NAME	Pending	Y	PAM config PAM Pending Safe Name. Note: safe must already exist and pamuser can add and change accounts.
Environment variable	BRIMSTONE_URL	http://brimstone.example.com:9191	Y	URL where to post hashes
Environment variable	BRIMSTONE_API_KEY	BRIMSTONE_API_KEY	N	default env var name is BRIMSTONE_API_KEY

Using an .env file

• Copy .env.example to .env and fill the values
• Start Brimstone or Hailstone using the .env file

(env $(cat .env | sed 's/#.*//g' | xargs) bin/brimstone)
# or
(env $(cat .env | sed 's/#.*//g' | xargs) bin/hailstone)

Walk Through

Setup

• Create a GitGuardian account
• Create a GitHub repo and connect it to Gitguardian
• Create a safe in PAM vault to be used for new accounts, for this example "Pending" safe is used
• Deploy Brimstone where it can be accessed by GG custom webhook (see table for parameters)
• Configure GG custom webhook to send "incident" types to Brimstone endpoint, /v1/notify/ggevent

GG Incident Flow

• In the GitHub repo, commit a secret and push it into GitHub
• Review the contents of the PAM safe for a new account

HMSL Leak Flow

• Run the "GG Incident Flow" to generate a GG Incident, and create an account in PAM vault safe
• Run Hailstone app to load Brimstone with the secrets from the pending safe (Note: a user that has access to the pending safe is required)
• Call the send full hashes endpoint in Brimstone GET /v1/hashes/sendfullhashes -- this will send all the hashes in Brimstone to the HMSL service
• Review the contents of the pending safe and find the account, it should show that it requires a password change

References

• Learn more about HasMySecretLeaked

• The Trustless and Secure Protocol powering HasMySecretLeaked

• Documentation of HasMySecretLeaked's API

• Other projects

  • CyberArk Conjur
  • CyberArk

Technologies

• go "1.21.5"

• cockroach db "Build Tag: v23.1.11"

• openapi "3.0.0"

  • oapi-codegen "v1.16.2"
  • Optional
    • npm "10.2.4"
    • redocly "1.6.0"

• Optional document tools

  • doctoc "doctoc@2.2.1"
  • plantuml "v1.2023.12"
  • dot "dot - graphviz version 2.43.0 (0)"

Colophon

Brimstone - archaic term for sulfur -> sulfur is the stuff "matches" are made from. Brimstone, the app, curates the stuff "matches" are made from. E.g., the hashes are matched with other hashes.

License

Copyright (c) 2024 CyberArk Software Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For the full license text see LICENSE.

Contributing

We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our contributing guide.

Code of Conduct.