How to Configure Gene-EmailSecurity — API Key Setup & Vault Configuration

Overview

Gene-EmailSecurity requires configuring API keys for the tools that use third-party services. This guide walks you through signing up for free API keys, configuring them in Feluda Vault, and verifying that your setup is working correctly.

Important: Eight of the 18 tools work without any API keys at all. You only need to configure the keys for the services you plan to use. The DNS-based tools and utility tools work immediately after deployment.

API Keys Required

The following six API keys are used by Gene-EmailSecurity. All are free:

Secret Name	Service	Sign Up URL	Free Tier Limits
EMAILREP_API_KEY	EmailRep.io	https://emailrep.io/signup	1,000 requests/day
HIBP_API_KEY	HaveIBeenPwned	https://haveibeenpwned.com/API/Key	Rate limited per IP
HUNTER_API_KEY	Hunter.io	https://hunter.io/signup	25 requests/month (free)
ABUSEIPDB_API_KEY	AbuseIPDB	https://www.abuseipdb.com/register	1,000 requests/day
URLSCAN_API_KEY	URLScan.io	https://urlscan.io/user/signup	10 requests/minute
SAFEBROWSING_API_KEY	Google Safe Browsing	https://developers.google.com/safe-browsing/v4/get-started	10,000 requests/day

Step 1: Sign Up for API Keys

EMAILREP_API_KEY (EmailRep.io)

1. Go to https://emailrep.io/signup
2. Create an account using your email address
3. Once logged in, you'll find your API key in your account dashboard
4. Copy the key for use in Feluda Vault

HIBP_API_KEY (HaveIBeenPwned)

1. Go to https://haveibeenpwned.com/API/Key
2. Enter your email address
3. You'll receive an email with a confirmation link
4. Click the link to receive your API key

HUNTER_API_KEY (Hunter.io)

1. Go to https://hunter.io/signup
2. Sign up for a free account
3. Once logged in, navigate to your dashboard
4. Click "API" in the navigation menu
5. Copy your API key

ABUSEIPDB_API_KEY (AbuseIPDB)

1. Go to https://www.abuseipdb.com/register
2. Create a free account
3. Once logged in, navigate to your account settings
4. You'll find your API key in the "API" section

URLSCAN_API_KEY (URLScan.io)

1. Go to https://urlscan.io/user/signup
2. Create a free account
3. Once logged in, navigate to your API settings
4. You'll find your API key available for copying

SAFEBROWSING_API_KEY (Google Safe Browsing)

1. Go to https://developers.google.com/safe-browsing/v4/get-started
2. You'll need a Google Cloud Platform project
3. Create or select a project
4. Enable the Safe Browsing API
5. Create an API key
6. Copy the API key

Step 2: Configure Secrets in Feluda Vault

Once you have all six API keys, you need to configure them in Feluda Vault so the tools can access them.

Method 1: Through Feluda Desktop Application

1. Open the Feluda Desktop Application
2. Navigate to the Vault section
3. Click "Add Secret"
4. For each secret, add the following key-value pairs:

Secret Name	Value
EMAILREP_API_KEY	Your EmailRep.io API key
HIBP_API_KEY	Your HaveIBeenPwned API key
HUNTER_API_KEY	Your Hunter.io API key
ABUSEIPDB_API_KEY	Your AbuseIPDB API key
URLSCAN_API_KEY	Your URLScan.io API key
SAFEBROWSING_API_KEY	Your Google Safe Browsing API key

5. Save each secret after adding it

Method 2: Using the Gene Builder Tool

When you deploy Gene-EmailSecurity, the secrets are automatically detected and listed in the Vault. You can configure them through the Feluda UI.

Step 3: Verify Your Configuration

After configuring the secrets, test each tool to verify it's working correctly.

Test Tools Without API Keys (No Configuration Needed)

These tools work immediately after deployment:

1. ipGeolocation

   • Run: tool:ipGeolocation with ip=8.8.8.8
   • Expected: Geolocation data for 8.8.8.8

2. emailHeaderAnalyze

   • Run: tool:emailHeaderAnalyze with sample headers
   • Expected: Parsed header analysis

3. domainMXCheck, domainSPFCheck, domainDMARCCheck

   • Run with domain=google.com
   • Expected: DNS record data

Test Tools With API Keys

1. emailReputation (requires EMAILREP_API_KEY)

   • Run: tool:emailReputation with [email protected]
   • Expected: Reputation data for the email

2. breachCheck (requires HIBP_API_KEY)

   • Run: tool:breachCheck with [email protected]
   • Expected: Breach check results

3. emailForwardCheck (requires HUNTER_API_KEY)

   • Run: tool:emailForwardCheck with [email protected]
   • Expected: Email verification results

4. ipReputation (requires ABUSEIPDB_API_KEY)

   • Run: tool:ipReputation with ip=8.8.8.8
   • Expected: IP reputation data

5. safeBrowsingCheck (requires SAFEBROWSING_API_KEY)

   • Run: tool:safeBrowsingCheck with url=https://google.com
   • Expected: Safe Browsing results

Troubleshooting

Tool Returns "Secret Not Configured"

This means the API key is not set in Feluda Vault.

• Check that you've added the secret to Vault
• Verify the secret name matches exactly (e.g., EMAILREP_API_KEY)
• Restart Feluda after adding secrets

Tool Returns HTTP 401 or 403 Error

This means the API key is invalid or expired.

• Verify you copied the correct API key
• Check if the API key has expired
• Regenerate the key if necessary

Tool Returns HTTP 429 (Too Many Requests)

This means you've exceeded the rate limit for the free tier.

• Wait for the rate limit window to reset
• Consider upgrading to a paid tier if you need higher limits

Tool Returns HTTP 404 (Not Found)

This is a normal response when:

• An email has no reputation data (emailReputation)
• An email has no breach history (breachCheck)
• A domain has no specific DNS record

Next Steps

Once your API keys are configured, you can:

1. Use the AI prompts — phishingInvestigator and emailThreatAdvisor — for guided investigations
2. Integrate the tools into your SOC workflows
3. Create RunFlows that automate common investigation patterns
4. Explore the DNS authentication tools for domain security audits

You can configure only the keys you need and add more later. The gene remains functional with partial configuration.