# MalwareGuard Partner API

Use this API when another project needs a simple malware verdict for a URL or
Windows PE file.

## Deployments

- Frontend on Vercel: `https://malwareguard-one.vercel.app`
- Backend on Hugging Face Space: `https://heshamxor-malwareguard.hf.space`
- Recommended public API base URL through Vercel: `https://malwareguard-one.vercel.app/api/partner`
- Direct backend API base URL: `https://heshamxor-malwareguard.hf.space/api/partner`

The Vercel app rewrites `/api/*` requests to the Hugging Face backend, so partner
projects can use the Vercel base URL and avoid browser CORS issues.

## Authentication

Production deployments should set:

```env
PARTNER_API_KEYS=shared-secret-key
```

Partners must send the key in every request:

```http
X-API-Key: shared-secret-key
```

If partners call the API directly from a browser frontend, add their deployed
frontend origin to the backend `CORS_ORIGINS` environment variable.

If multiple groups need access, set comma-separated keys:

```env
PARTNER_API_KEYS=group-a-key,group-b-key
```

## Health

```bash
curl https://malwareguard-one.vercel.app/api/partner/health \
  -H "X-API-Key: shared-secret-key"
```

## Analyze a URL

```bash
curl -X POST https://malwareguard-one.vercel.app/api/partner/analyze-url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: shared-secret-key" \
  -d '{"url":"https://example.com/login"}'
```

Response:

```json
{
  "analysis_type": "url",
  "target": "https://example.com/login",
  "verdict": "Malicious",
  "is_malicious": true,
  "malicious_score": 0.84,
  "confidence_level": "High",
  "threshold_used": 0.5,
  "source": "malwareguard-url-hypermodel",
  "details": {
    "base_model_scores": {},
    "top_signals": {}
  }
}
```

## Analyze a File

Only Windows PE files are supported, such as `.exe`, `.dll`, and `.sys`.
Maximum file size is 200 MB for partner API keys.

```bash
curl -X POST https://malwareguard-one.vercel.app/api/partner/analyze-file \
  -H "X-API-Key: shared-secret-key" \
  -F "file=@sample.exe"
```

Response:

```json
{
  "analysis_type": "file",
  "target": "sample.exe",
  "verdict": "Malicious",
  "is_malicious": true,
  "malicious_score": 0.91,
  "confidence_level": "High",
  "threshold_used": 0.5,
  "source": "malwareguard-ember-xgboost",
  "sha256": "file_sha256_hash",
  "file_size": 123456,
  "feature_count": 2381,
  "inference_time_ms": 3.2,
  "details": {}
}
```

## Analyze a Generic File (CSV, MP4)

Supported generic files include `.csv`, `.tsv`, `.mp4`, `.m4v`, `.mov`.
Maximum file size is 200 MB for partner API keys.

```bash
curl -X POST https://malwareguard-one.vercel.app/api/partner/analyze-generic \
  -H "X-API-Key: shared-secret-key" \
  -F "file=@data.csv"
```

Response:

```json
{
  "analysis_type": "file",
  "target": "data.csv",
  "verdict": "Malicious",
  "is_malicious": true,
  "malicious_score": 0.99,
  "confidence_level": "High",
  "threshold_used": 0.5,
  "source": "malwareguard-csv-xgboost",
  "sha256": "file_sha256_hash",
  "file_size": 1234,
  "details": {
    "threats": [
      {
        "type": "Formula Injection",
        "severity": "Critical",
        "description": "Found DDE injection payload"
      }
    ]
  }
}
```