/cyberark-gitguardian-hmsl-remediation-integration-service

Primary LanguageGoApache License 2.0Apache-2.0

CyberArk Banner

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.

Scenario 2 Diagram

Scenario 2 Diagram

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

Parameter Example Value Required Notes
-keyvar BRIMSTONE_API_KEY N default env var name is BRIMSTONE_API_KEY
-hmslurl 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
-hmslaudtype hmsl N Audience type for HMSL JWT request, default value is hmsl
-ggapiurl https://api.gitguardian.com N GG API URL, default is https://api.gitguardian.com
-ggapitokenvar 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)
-ggwebhooktokenvar GG_WEBHOOK_TOKEN_VARNAME Y GG API Token env var contains GG API token to use (default env var name: GG_WEBHOOK_TOKEN)
-dburl postgresql://root@localhost:26257/brimstone?sslmode=disable&application_name=brimstone N Database URL, default value is postgresql://root@localhost:26257/brimstone?sslmode=disable&application_name=brimstone
-port 9191 N Port whereon Brimstone listens, default: 9191
-idtenanturl https://EXAMPLE.id.cyberark.cloud Y PAM config ID tenant URL
-pcloudurl https://EXAMPLE.privilegecloud.cyberark.cloud Y PAM config Privilege Cloud URL
-pamuser pam user Y PAM config PAM User
-pampass pam user password Y PAM config PAM Pass
-safename Pending Y PAM config PAM Pending Safe Name. Note: safe must already exist and pamuser can add and change accounts.
-version N Print version and exit
-d N Set output level to debug

Hailstone App

Parameter Example Value Required Notes
-d N enable debug mode
-idtenanturl https://EXAMPLE.id.cyberark.cloud Y ID Tenant
-pcloudurl https://EXAMPLE.privilegecloud.cyberark.cloud Y Privilege Cloud (or PAM self-hosted)
-pamuser pamuser@example.com Y PAM user - must have perms to add account and change account password
-pampass mypassword Y PAM user creds
-safename pendingsafe Y Safe name for Pending safe where new accounts will be added
-brimstoneurl http://brimstone.example.com:9191/v1/hashes Y URL where to post hashes
-brimstoneapikey abc123 Y API key to authn to Brimstone service

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

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.