# CVE Lookup Tool - Quick Start Guide

## Installation & Deployment

### Local Development
```bash
cd /home/deeptechadmin/hf/spaces/cve-lookup/
pip install -r requirements.txt
python -m gradio app.py
```

### Hugging Face Spaces
1. Create a new Space on Hugging Face with Gradio SDK
2. Upload the three files:
   - app.py
   - requirements.txt
   - README.md
3. Space will automatically build and launch

## Interface Overview

### Tab 1: Search CVE
- **Input**: CVE ID or keyword
- **Output**: Detailed vulnerability information
- **Features**:
  - Search by exact CVE ID: `CVE-2021-44228`
  - Search by keyword: `log4j`, `apache`, `exchange`
  - Results show CVSS, severity, affected products, dates
  - Color-coded severity indicators

### Tab 2: Top CVEs
- Browse 50 most critical CVEs
- Sortable columns by CVE ID, Name, Score, Severity
- Instant access to trending vulnerabilities
- Perfect for security awareness

### Tab 3: Statistics
- Visual charts of CVE distribution
- By publication year
- By severity level
- Summary statistics cards

## Search Examples

1. **Find specific CVE**: `CVE-2021-44228`
2. **Find by product**: `apache`, `windows`, `nginx`
3. **Find by CVE name**: `log4shell`, `eternal`, `proxy`
4. **Find by year**: (use top CVEs tab and filter)

## Key Features

### Color Coding
- Red: Critical (9.0-10.0 CVSS)
- Orange: High (7.0-8.9 CVSS)
- Yellow: Medium (4.0-6.9 CVSS)
- Green: Low (0-3.9 CVSS)

### Data Sources
- NVD API (National Vulnerability Database)
- Built-in curated database
- Real-time updates available via API

### Language Support
- English
- Francais (French)
- Bilingual descriptions for critical CVEs

## Integration with Security Workflows

### SOC (Security Operations Center)
1. Ingest new vulnerability alerts
2. Quick lookup using CVE ID
3. Cross-reference with asset database
4. Assess organizational impact

### Penetration Testing
1. Research target vulnerabilities
2. Review affected versions
3. Check CVSS score for prioritization
4. Reference documentation

### Threat Intelligence
1. Monitor trending CVEs
2. Track critical vulnerabilities
3. Share intelligence with stakeholders
4. Generate reports

## API Integration

The tool uses the NVD API v2.0:
```
https://services.nvd.nist.gov/rest/json/cves/2.0
```

Features:
- Real-time vulnerability data
- Fallback to built-in database if API unavailable
- Automatic error handling
- 10-second timeout to prevent hangs

## Database Structure

Each CVE entry contains:
- CVE ID (unique identifier)
- Name/Alias
- English description
- French description
- CVSS score (0-10)
- Severity level (CRITICAL, HIGH, MEDIUM, LOW)
- Affected products/versions
- Publication year
- Full publication date

## Performance Notes

- Built-in database: Instant results
- NVD API queries: 1-3 seconds typical
- Statistics generation: < 500ms
- Supports concurrent users

## Customization

To add more CVEs to the built-in database:

1. Open app.py
2. Find `BUILTIN_CVES = [` (around line 11)
3. Add entries following the structure:
   ```python
   {
       "id": "CVE-YYYY-XXXXX",
       "name": "Vulnerability Name",
       "description_en": "English description...",
       "description_fr": "French description...",
       "cvss": 8.5,
       "severity": "HIGH",
       "products": "Affected software/versions",
       "year": 2022,
       "published": "YYYY-MM-DD"
   }
   ```

## Troubleshooting

### NVD API Not Responding
- Tool automatically falls back to built-in database
- Check your internet connection
- NVD API may have rate limits

### Performance Issues
- Clear browser cache
- Restart the Gradio server
- Check system resources

### Language Not Changing
- Refresh the page
- Clear browser cookies
- Try a different language setting

## Support & Contact

For issues, suggestions, or additional CVE entries:
- Visit: https://ayinedjimi-consultants.fr
- Contact: security@ayinedjimi-consultants.fr

## License

Apache License 2.0 - Free for commercial and personal use

---

Last Updated: February 2025
Version: 1.0