SecretHound

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 21 Open GitHub ↗

An OpenGraph extension for secrets

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SecretHound - A BloodHound OpenGraph Extension for Secrets
<p align="center">
  <img src="assets/logo.png" alt="SecretHound Logo" width="400"/>
</p>

## Overview

SecretHound is a BloodHound OpenGraph extension for secret scanning results. By converting credential discoveries from multiple security scanning tools into BloodHound's OpenGraph format, SecretHound enables security teams to identify and analyze hybrid attack paths that span multiple technology environments.

For a detailed discussion of the multi-subgraph approach to attack path analysis, see the associated [blog post](https://specterops.io/blog/2025/11/13/taming-the-attack-graph-a-many-subgraphs-approach-to-attack-path-analysis/). SecretHound is built on the [bhopengraph](https://github.com/p0dalirius/bhopengraph) library by @p0dalirius.

### Key Features

- **Multi-Scanner Support**: Integrates with GitHub Secret Scanning, NoseyParker, TruffleHog, and Nemesis
- **Hybrid Attack Path Analysis**: Maps discovered secrets to 141 technology subgraphs
- **Standardized Graph Integration**: Uses the `ContainsCredentialsFor` edge type to connect credentials to accessible infrastructure
- **Technology Taxonomy**: Automated classification system supporting major cloud providers (AWS, Azure, GCP) and enterprise services

### Supported Scanners

- GitHub Secret Scanning
- NoseyParker
- TruffleHog
- Nemesis

## Installation
```bash
git clone https://github.com/C0KERNEL/SecretHound.git
cd SecretHound
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Quick Start

```bash
# Retrieve GitHub Secret Scanning alerts for an org:
gh api /orgs/ORG/secret-scanning/alerts > github_alerts.json

# Parse GitHub Secret Scanning alerts with SecretHound (redacts by default)
python secrethound.py -t github -i github_alerts.json -o og_secrets.json

# Register technology icons in BloodHound (one-time setup)
python custom_icons.py --token YOUR_BLOODHOUND_TOKEN

# Upload og_secrets.json to BloodHound via the UI
```

## Workflow Example using NoseyParker

```bash
# 1. Scan this repository with NoseyParker
git clone https://github.com/C0KERNEL/SecretHound.git
noseyparker scan --datastore np.db SecretHound
noseyparker report --datastore np.db --format json > noseyparker_output.json

# 2. Convert to BloodHound format
python secrethound.py -t noseyparker -i noseyparker_output.json -o bloodhound_secrets.json -v

# 3. Register technology icons in BloodHound (one-time setup)
python custom_icons.py --token YOUR_BLOODHOUND_TOKEN

# 4. Upload bloodhound_secrets.json to BloodHound CE via web UI

# 5. Query using Cypher in BloodHound interface
```

## Usage

### Command Line Interface
```bash
python secrethound.py -t {github,noseyparker,trufflehog,nemesis} -i INPUT -o OUTPUT [OPTIONS]
```
### Arguments

| Argument | Description |
|----------|-------------|
| `-t, --type` | Scanner type: github, noseyparker, trufflehog, or nemesis (required) |
| `-i, --input` | Input file path (JSON or JSONL) (required) |
| `-o, --output` | Output BloodHound JSON file path (required) |
| `--no-redact` | Include full secrets in output (WARNING: Sensitive data will be stored in BloodHound nodes) |
| `--source-kind` | Source kind for BloodHound OpenGraph (default: StargateNetwork) |
| `-v, --verbose` | Enable verbose logging |

## Technology Taxonomy
SecretHound uses a comprehensive taxonomy to automatically categorize secrets by technology. The taxonomy maps scanner-specific rule IDs to BloodHound node types, covering 200+ TruffleHog detectors and all NoseyParker and GitHub Secret Scanning rules.

### Node Kind System
All nodes and edges produced by SecretHound are tagged with the `StargateNetwork` source_kind. This naming convention reflects the tool's core functionality: discovered credentials serve as "portals" that enable access to different technology subgraphs within the BloodHound attack graph. When a credential is found in one environment (such as a Git repository), it can provide direct access to an entirely separate infrastructure subgraph (such as AWS, Azure, or GCP), similar to a network of interconnected gateways.

Secrets are categorized using a dual-classification system: technology-specific secrets receive a `*Secret` kind paired with their corresponding `*Base` kind, while unclassified secrets are assigned a generic `Secret` kind.

Specific `AWSSecret` kind based on `AWSBase` example:
```json
{
  "kinds": ["AWSSecret", "AWSBase"],
  "properties": {
    "secret_type": "AWS Secret Access Key",
    "secret_value_redacted": "AKIA...KEY"
  }
}
```

Generic `Secret` example:
```json
{
  "kinds": ["Secret"],
  "properties": {
    "secret_type": "Generic Secret",
    "secret_value_redacted": "pass...word"
  }
}
```

This enables powerful Cypher queries across `kind` values:
- `MATCH (s:StargateNetwork) RETURN s` - All nodes generated by this tool
- `MATCH (s:Secret) RETURN s` - All secrets
- `MATCH (s:AWSBase) RETURN s` - All AWS-related nodes
- `MATCH (s:AWSSecret) RETURN s` - Only AWS Secrets
- `MATCH (s:GHBase) RETURN s` - All GitHub nodes
- `MATCH (s:GHSecret) RETURN s` - All GitHub secrets

### Technology Color Scheme

Each technology uses colors for visualization:

| Technology | Node Kinds | Hex Color |
|------------|-----------|-----------|
| AWS | AWSSecret | `#FF9900` |
| Azure |AZSecret | `#0078D4` |
| GCP | GCPSecret | `#4285F4` |
| GitHub | GHSecret | `#181717` |
| ... | ... | `...` |
| Default | Secret | `#ffc800` |

See `taxonomy/taxonomy.json` for the complete list technologies.

### Registering Icons in BloodHound
After generating your BloodHound data, register the technology icons:

```bash
# Register icons in BloodHound
python custom_icons.py --token YOUR_BLOODHOUND_TOKEN

# Use custom BloodHound URL
python custom_icons.py --token YOUR_TOKEN --url http://bloodhound.local:8080/api/v2/custom-nodes
```

## Scanner-Specific Examples
### GitHub Secret Scanning
```bash
# Export alerts from GitHub
gh api /orgs/YOUR_ORG/secret-scanning/alerts > github_alerts.json

# Convert to BloodHound OpenGraph
python secrethound.py -t github -i github_alerts.json -o og_secrets.json
```

### NoseyParker
```bash
# Scan a repository
noseyparker scan --datastore np.db --git-url https://github.com/example/repo.git

# Generate JSON report
noseyparker report --datastore np.db --format json > noseyparker_output.json

# Convert to BloodHound OpenGraph
python secrethound.py -t noseyparker -i noseyparker_output.json -o og_secrets.json
```

### TruffleHog
```bash
# Scan with TruffleHog
trufflehog git https://github.com/example/repo.git --json > trufflehog_output.jsonl

# Convert to BloodHound OpenGraph
python secrethound.py -t trufflehog -i trufflehog_output.jsonl -o og_secrets.json
```

### Nemesis
```bash
# Export data from Nemesis and convert
python scripts/fetch_nemesis_findings.py --api-key <Hasura GraphQL API key> > nemesis_export.json

# Convert to BloodHound OpenGraph
python secrethound.py -t nemesis -i nemesis_export.json -o og_secrets.json
```

## BloodHound Query Examples

The following Cypher queries demonstrate how to leverage SecretHound's node kind system for attack path analysis:

```cypher
// Find all secrets
MATCH (s:Secret) RETURN s

// Find only AWS Secret Access Keys
MATCH (s:AWSSecret) RETURN s

// Find nodes added by SecretHound
MATCH (s:StargateNetwork) RETURN s

// Find paths using secrets
MATCH p=(r:StargateNetwork)-[:ContainsCredentialsFor]->(s:StargateNetwork)
RETURN p

// Find hybrid attack paths to Azure
MATCH p=(s:StargateNetwork)-[r*..]->(t:AZBase)
RETURN p

// Find hybrid attack paths to AWS
MATCH p=(s:StargateNetwork)-[r*..]->(t:AWSBase)
RETURN p

// Find hybrid attack paths to GCP
MATCH p=(s:StargateNetwork)-[r*..]->(t:GCPBase)
RETURN p
```

## OpenGraph Compatibility

SecretHound is designed to integrate with existing (and future) BloodHound OpenGraph extensions:

**Compatible Extensions:**
- [GitHound](https://github.com/SpecterOps/GitHound) - GitHub repository and user mapping (integration in progress)
- [GCP-Hound](https://github.com/F41zK4r1m/GCP-Hound) - GCP technology subgraph using `GCPBase` kind

## Acknowledgments

SecretHound builds upon the work of several open-source projects and organizations:

- **SpecterOps** - BloodHound, OpenGraph specification, GitHound, and Nemesis platform
- **Praetorian** - NoseyParker secret scanner
- **TruffleSecurity** - TruffleHog secret detection
- **LeakTK** - fake-leaks testing repository
- **p0dalirius** - bhopengraph library

## References

- [BloodHound Enterprise](https://specterops.io/bloodhound-enterprise/) / [BloodHound CE](https://github.com/SpecterOps/BloodHound)
- [OpenGraph](https://bloodhound.specterops.io/opengraph/best-practices)
- [GitHound](https://github.com/SpecterOps/GitHound)
- [Nemesis](https://github.com/SpecterOps/Nemesis)
- [NoseyParker](https://github.com/praetorian-inc/noseyparker)
- [TruffleHog](https://github.com/trufflesecurity/trufflehog)
- [LeakTK](https://github.com/leaktk/fake-leaks)
- [bhopengraph](https://github.com/p0dalirius/bhopengraph)

SecretHound

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README