@@ -45,6 +45,13 @@ vendor/
 .env
 *.env.local
 
+# Config files with API keys/secrets (user-specific configs)
+**/config/**/config.yaml
+!config/examples/*.yaml
+!config/client/default.yaml
+*-config.yaml
+**/proxyhawk/config.yaml
+
 # Go workspace file
 go.work
 
 
@@ -0,0 +1,234 @@
+# Security Notice - API Keys and Sensitive Configuration
+
+**IMPORTANT**: This document explains how to safely use ProxyHawk with API keys and sensitive configuration data.
+
+---
+
+## ⚠️ NEVER Commit API Keys to Git
+
+### Protected by .gitignore
+
+The following patterns are automatically ignored by git to prevent accidental commits of sensitive data:
+
+```gitignore
+# Config files with API keys/secrets (user-specific configs)
+**/config/**/config.yaml
+!config/examples/*.yaml
+!config/client/default.yaml
+*-config.yaml
+**/proxyhawk/config.yaml
+
+# Environment files
+.env
+*.env.local
+```
+
+### Safe Config Locations
+
+✅ **These locations are safe** (ignored by git):
+- `~/.config/proxyhawk/config.yaml` - User config directory
+- Any file matching `*-config.yaml` pattern (e.g., `shodan-config.yaml`, `test-config.yaml`)
+- `/tmp/` directory files (outside repository)
+
+❌ **These locations are NOT safe** (would be committed):
+- `config/default.yaml` - DO NOT add API keys here
+- Any config file in the repository without `-config` suffix
+
+---
+
+## How to Use API Keys Safely
+
+### Method 1: User Config Directory (Recommended)
+
+Create your config in the user directory:
+
+```bash
+mkdir -p ~/.config/proxyhawk
+cat > ~/.config/proxyhawk/config.yaml << 'EOF'
+timeout: 10
+discovery:
+  shodan_api_key: "YOUR_ACTUAL_SHODAN_KEY_HERE"
+  censys_api_key: "YOUR_CENSYS_KEY_HERE"
+  censys_secret: "YOUR_CENSYS_SECRET_HERE"
+EOF
+```
+
+Then run ProxyHawk without specifying `-config` (it will automatically find it):
+```bash
+./proxyhawk -discover -discover-source shodan
+```
+
+### Method 2: Custom Config File with Safe Name
+
+Create a config file with `-config` suffix:
+
+```bash
+cat > my-shodan-config.yaml << 'EOF'
+discovery:
+  shodan_api_key: "YOUR_KEY_HERE"
+EOF
+
+./proxyhawk -discover -config my-shodan-config.yaml
+```
+
+### Method 3: Temporary Directory
+
+For testing, use `/tmp/`:
+
+```bash
+cat > /tmp/test-config.yaml << 'EOF'
+discovery:
+  shodan_api_key: "YOUR_KEY_HERE"
+EOF
+
+./proxyhawk -discover -config /tmp/test-config.yaml
+```
+
+---
+
+## Example Configs
+
+### ✅ Safe Example (No Real Keys)
+
+`config/examples/discovery-example.yaml`:
+```yaml
+discovery:
+  shodan_api_key: "YOUR_SHODAN_API_KEY_HERE"  # ✅ Placeholder only
+  censys_api_key: "YOUR_CENSYS_API_KEY_HERE"
+```
+
+This is safe to commit because it contains only placeholders.
+
+### ❌ Unsafe Example (Real Keys)
+
+**NEVER create a file like this in the repository**:
+```yaml
+discovery:
+  shodan_api_key: "eFqvPM5H0WvAIS49LNs4aZrNDBgEZYrG"  # ❌ REAL KEY - DO NOT COMMIT!
+```
+
+---
+
+## Checking What Would Be Committed
+
+Before committing, always check:
+
+```bash
+# See what files are staged
+git status
+
+# Check if a specific file would be ignored
+git check-ignore my-config.yaml
+
+# Check all tracked files in config directory
+git ls-files config/
+```
+
+If you see any config files with actual API keys listed in `git status`, **DO NOT COMMIT THEM**.
+
+---
+
+## What to Do if You Accidentally Committed a Key
+
+If you accidentally committed an API key:
+
+1. **Immediately revoke the key** on the provider's website
+   - Shodan: https://account.shodan.io/
+   - Censys: https://search.censys.io/account
+
+2. **Generate a new key**
+
+3. **Remove the key from git history**:
+   ```bash
+   # Remove the file from git history
+   git filter-branch --force --index-filter \
+     "git rm --cached --ignore-unmatch path/to/config-with-key.yaml" \
+     --prune-empty --tag-name-filter cat -- --all
+
+   # Or use BFG Repo-Cleaner (faster):
+   # bfg --delete-files config-with-key.yaml
+   ```
+
+4. **Force push** (if already pushed to remote):
+   ```bash
+   git push origin --force --all
+   ```
+
+5. **Update your local config** with the new key
+
+---
+
+## Environment Variables (Alternative)
+
+You can also use environment variables instead of config files:
+
+```bash
+export PROXYHAWK_SHODAN_KEY="your_key_here"
+export PROXYHAWK_CENSYS_KEY="your_key_here"
+export PROXYHAWK_CENSYS_SECRET="your_secret_here"
+
+# Then ProxyHawk can read from environment
+./proxyhawk -discover
+```
+
+**Note**: This feature would need to be implemented. Currently, API keys must be in config files.
+
+---
+
+## GitHub Secrets (For CI/CD)
+
+If running ProxyHawk in GitHub Actions, use GitHub Secrets:
+
+1. Go to repository Settings → Secrets and variables → Actions
+2. Add secrets:
+   - `SHODAN_API_KEY`
+   - `CENSYS_API_KEY`
+   - `CENSYS_SECRET`
+
+3. Reference in workflow:
+   ```yaml
+   - name: Run ProxyHawk Discovery
+     env:
+       SHODAN_KEY: ${{ secrets.SHODAN_API_KEY }}
+     run: |
+       echo "discovery:" > config.yaml
+       echo "  shodan_api_key: \"$SHODAN_KEY\"" >> config.yaml
+       ./proxyhawk -discover -config config.yaml
+   ```
+
+---
+
+## Summary
+
+✅ **DO**:
+- Store API keys in `~/.config/proxyhawk/config.yaml`
+- Use config files with `-config` suffix (e.g., `my-config.yaml`)
+- Test with files in `/tmp/` directory
+- Use placeholder values in committed example configs
+- Double-check `git status` before committing
+
+❌ **DON'T**:
+- Commit real API keys to the repository
+- Store keys in `config/default.yaml`
+- Push configs with real keys to GitHub
+- Share config files with keys in chat/email
+
+---
+
+## .gitignore Protection Status
+
+Current protection level: **STRONG** ✅
+
+Protected patterns:
+- `**/config/**/config.yaml` - Any nested config.yaml
+- `*-config.yaml` - Any file ending with `-config.yaml`
+- `**/proxyhawk/config.yaml` - ProxyHawk config directories
+- `.env` and `*.env.local` - Environment files
+
+Exceptions (safe to commit):
+- `config/examples/*.yaml` - Example configs with placeholders
+- `config/client/default.yaml` - Default config template
+
+---
+
+**Remember**: When in doubt, use `~/.config/proxyhawk/config.yaml` - it's always safe!