# HackerOne Hybrid MCP Server

Serveur MCP complet et hybride pour **HackerOne**, combinant :
1. **L'API REST v1 HackerOne** (HTTP Basic Auth avec vos identifiants d'API) pour la rapidité et la fiabilité.
2. **Session Web persistante (Playwright / Patchright)** pour accéder aux rapports publics complets (Hacktivity PoCs, scopes et discussions) protégés par Cloudflare.

> ✅ **Portabilité** : Ce serveur MCP est 100% portable et fonctionne de manière identique sur **Windows, Linux et macOS**.
> Aucun chemin n'est codé en dur : tous les chemins sont résolus dynamiquement (`os.path.expanduser`, variables d'environnement).

---

## 🐧 Installation rapide sous Linux

```bash
cd hackerone-mcp
chmod +x install.sh
./install.sh
```

Le script `install.sh` crée l'environnement virtuel, installe les dépendances et télécharge Chromium anti-détection.

---

## 🛠️ Outils disponibles dans ce MCP

### 1. Outils API REST Officiels
* **`h1_get_my_reports`** : Liste tous les rapports et vulnérabilités soumis par votre compte.
* **`h1_get_report_details`** : Affiche les détails complets d'un rapport spécifique par son identifiant.
* **`h1_submit_report`** : Soumet un nouveau rapport de vulnérabilité (handle du programme, titre, steps to reproduce, impact, sévérité).
* **`h1_get_earnings`** : Consultez vos gains totaux, balance actuelle et historique des payouts / bounties reçus.
* **`h1_get_hacktivity`** : Récupère le flux public des dernières vulnérabilités résolues.
* **`h1_get_program`** : Récupère le scope et les informations d'un programme officiel.

### 2. Outils Web Avancés (Session Persistante)
* **`h1_web_read_disclosed_report`** : Lit l'intégralité d'un rapport public HackerOne (`https://hackerone.com/reports/<id>`), incluant les messages de triage, les PoCs détaillés et les primes accordées.
* **`h1_web_search_disclosed`** : Recherche des writeups et PoCs réels dans le Hacktivity avec vos mots-clés (ex: `SSRF AWS`, `OAuth bypass`, `GraphQL`).
* **`h1_web_view_program_policy`** : Affiche la politique complète et les tables de bounty d'un programme directement sur le web.

---

## 🚀 Installation & Configuration

### Étape 1 : Créer l'environnement virtuel et installer les dépendances

Dans le dossier `D:\Steph\File\Projet\MCP\hackerone-mcp` :

```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
patchright install chromium
```

---

### Étape 2 : Configurer vos clés d'accès API

1. Rendez-vous sur votre compte HackerOne dans les paramètres d'API :  
   👉 [https://hackerone.com/settings/api_token/edit](https://hackerone.com/settings/api_token/edit)
2. Créez un token d'API.
3. Remplissez le fichier `.env` :

```ini
H1_USERNAME=votre_pseudo_hackerone
H1_API_TOKEN=votre_cle_api_generee
```

---

### Étape 3 : Initialiser la session Web (Playwright)

Pour permettre au MCP de lire les writeups protégés par Cloudflare et accéder à votre dashboard web :

```powershell
python auth.py
```

* Une fenêtre de navigateur s'ouvre.
* Connectez-vous avec vos identifiants (Mot de passe / SSO Google / 2FA).
* Une fois sur le dashboard, **fermez la fenêtre**.
* Vos cookies de session sont sauvegardés dans `~/.hackerone-mcp/profile`.

---

## 🔌 Intégration Claude Desktop / MCP Clients

Ajoutez cette configuration dans votre `claude_desktop_config.json` ou `mcp_settings.json` :

```json
{
  "mcpServers": {
    "hackerone": {
      "command": "D:\\Steph\\File\\Projet\\MCP\\hackerone-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\Steph\\File\\Projet\\MCP\\hackerone-mcp\\server.py"
      ],
      "env": {
        "H1_USERNAME": "votre_pseudo",
        "H1_API_TOKEN": "votre_token"
      }
    }
  }
}
```

### Sous Linux / macOS :

```json
{
  "mcpServers": {
    "hackerone": {
      "command": "/chemin/vers/hackerone-mcp/.venv/bin/python",
      "args": [
        "/chemin/vers/hackerone-mcp/server.py"
      ],
      "env": {
        "H1_USERNAME": "votre_pseudo",
        "H1_API_TOKEN": "votre_token"
      }
    }
  }
}
```

---

## 🔒 Sécurité de vos identifiants

* Vos identifiants (`H1_USERNAME` / `H1_API_TOKEN`) ne sont **jamais** loggés, envoyés à un service tiers, ou inclus dans le code source. Ils sont utilisés **uniquement** en mémoire pour signer les requêtes HTTP Basic vers `api.hackerone.com`.
* Le fichier `.env` est exclu du versioning via `.gitignore`.
* Le profil navigateur (`~/.hackerone-mcp/profile`) contient vos cookies de session et reste local à votre machine.

---

## ⚠️ Portabilité : détails techniques

| Fonctionnalité | Windows | Linux | macOS |
|:---|:---:|:---:|:---:|
| API REST (`h1_get_my_reports`, etc.) | ✅ | ✅ | ✅ |
| Session navigateur (`h1_web_*`) | ✅ | ✅ | ✅ |
| Chemin du profil utilisateur | `%USERPROFILE%\.hackerone-mcp\profile` | `~/.hackerone-mcp/profile` | `~/.hackerone-mcp/profile` |
| Détection de Chrome système | ✅ | ✅ | ✅ |
| Chromium Patchright embarqué | ✅ (auto-téléchargé) | ✅ (auto-téléchargé) | ✅ (auto-téléchargé) |

**Sous Linux**, si vous exécutez le navigateur en mode root ou dans un conteneur Docker, les flags `--no-sandbox` et `--disable-dev-shm-usage` sont déjà intégrés pour éviter les crashes de sandbox Chromium.