- Brimstone
Facilitate checking the existence of credential(s) found by GitGuardian with credentials(s) in PAM to see if they exist.
To keep credentials opaque, parts of hashes will be used as a proxy when doing comparisons. E.g. compare the hash of a credential to a similarly hashed password from PAM.
-
As a developer, when I commit and push a secret to a git repo that is connected to Gitguardian and that secret is in the PAM vault safe, I expect that secret to be detected, and then the vault notified to change that secret.
-
As a developer, when I commit and push a secret to a git repo that is connected to Gitguardian and that secret is not in a PAM vault safe, I expect that the secret to be detected, and then the vault notified to add an account with that secret.
-
As a PAM vault administrator, I can generate HMSL hashes for all accounts that I have access to and store them in Brimstone.
-
As an authorized Brimstone client, I can trigger Brimstone to send all HMSL hashes to the HasMySecretLeaked service. Furthermore, I expect the HMSL service responses to be processed whereby any leaked secrets that match an account in the vault will trigger the notification to the vault to change that secret.
The scope of the use cases is limited to interactions with GG and the PAM Vault. Other external services fall outside the scope of these use cases.
This is the scenario where GG has found a credential and it matches a credential in the PAM.
The action to take would be to rotate the credential inside PAM.
This is the scenario where GG has found a credential and it does not match a credential in the PAM.
The primary action to take would be to provision the credential into the PAM.
Implied Limitations:
- 1 brimstone running per 1 PAM instance
Provide an endpoint where credential hashes can be posted and persisted. Also, provide an enpoint where a scheduler can request to upload the hashes to HasMySecretLeaked.com.
Requirements:
- send full hash to GG to help dis-ambiguate
Base case:
-
Initial load of brimstone will load all creds from PAM using its API
- Hailstone will be a stand alone appilcation so that it can be run once, and reduce risk to leaking secrets from memory.
- Hailstone will use PAM API to fetch all account ids visible to the user account, then iterate over accounts to fetch secrets. The secrets will be hashed, then the hash values are stored for reference and uploading toHMSL
-
Fetch accounts - GET /PasswordVault/API/Accounts
-
Design Diagram
The database tables are auto-generated by GORM using the data models. This diagram shows what was generated.
Hash is defined in the OpenAPI Spec v3 doc in the api/brimstone.yaml file.
| Name | Type | Description |
|---|---|---|
| name | string | PAM Account ID |
| hash | string | Hash computed based on account object password value |
Rendered as JSON
{
"name": "PAM ACCOUNT ID",
"hash": "HASH STRING",
}HashBatch is defined in the OpenAPI Spec v3 doc in the api/brimstone.yaml file.
| Name | Type | Description |
|---|---|---|
| safename | string | PAM safe name |
| hashes | List<Hash> | List of Hash objects |
Rendered as JSON and used for /v1/hashses Request body
{
"safename": "SAFE NAME",
"hashes": [
{"name": "PAM ACCOUNT ID 1", "hash": "HASH STRING 1"},
{"name": "PAM ACCOUNT ID 2", "hash": "HASH STRING 2"},
{"name": "...", "hash": "..."},
{"name": "PAM ACCOUNT ID N", "hash": "HASH STRING N"}
]
}-
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]]
- Content-type header,
-
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
HashBatchstructure 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
- Requires Authorization Header,
-
GET /v1/hashes/sendhashes
- Requires Authorization Header,
Authorization: Bearer [[api key]] - Trigger brimstone to push current list of full hashes to HMSL
- Requires Authorization Header,
$ tree -d --prune --gitignore --noreport --info
├── api
│ { OpenSpec API docs
├── bin
│ { Binary builds
├── cmd
│ { Source for Go main commands
│ ├── brimstone
│ │ { Endpoint Server command
│ ├── ggclient
│ │ { Example client for Gitguardian API
│ ├── hailstone
│ │ { Tool to load Brimstone from PAM
│ ├── hmslclient
│ │ { Example client for HMSL API
│ ├── pamclient
│ │ { Example client for PAM API
│ └── randchar
│ { Utility to generate random characters
├── images
│ { Images for docs (generated images go here too)
├── pkg
│ ├── brimstone
│ │ { Source for Brimstone package (Generated code goes here too)
│ ├── gitguardian
│ │ { Source for gitguardian package (Generated from openapi spec)
│ ├── hasmysecretleaked
│ │ { Source for hasmysecretleaked package (Generated code goes here too)
│ ├── privilegeaccessmanager
│ │ { Source for PAM package
│ └── utils
│ { Source for helpers
├── scripts
│ { Build and Project support scripts
├── sql
│ { SQL to support Brimstone
├── static
│ { Generated html docs
-
Many tasks have targets rendered in the Makefile, run
makeormake helpfor list of targets -
Install cockroachdb https://www.cockroachlabs.com/docs/v23.1/install-cockroachdb
-
Start cockroachdb, there's a helper in the Makefile
make start-cockroach-dev
-
build all binaries
make build-all-bins
Make targets are also available to build individual binaries.
-
build brimstone
make build-brimstone
-
build hailstone
make build-hailstone
-
(Optional) generate API docs
make gen-brimstone-doc open static/brimstone-spec/index.html
-
Run brimstone server locally
-
Assuming that cockroachdb is running locally, then just start brimstone
# default db: "postgresql://root@localhost:26257/brimstone?sslmode=disable" # default listen port: 9191 ./bin/brimstone
-
If cockroachdb is running elsewhere, then provide
-dburlcommand line parameter -
If listening on another port for brimstone, then provide
-portcommand line parameter# set db url and endpoint listen port ./bin/brimstone -dburl "postgresql://user1@example.com:26257/brimstone" -port 11222
-
- https://www.gitguardian.com/hasmysecretleaked
- https://blog.gitguardian.com/announcing-has-my-secret-leaked
- https://blog.gitguardian.com/hasmysecretleaked-building-a-trustless-and-secure-protocol
- https://api.hasmysecretleaked.com/docs
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.
Copyright (c) 2023 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.
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.