<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Analyzing URL Reputation

## Agent Script

### Commands

| Command | Description |
|---|---|
| `node agent.js decompose <url>` | Decompose URL and flag indicators |
| `node agent.js defang <url>` | Defang URL for safe sharing |
| `node agent.js refang <url>` | Refang defanged URL for analysis |
| `node agent.js batch-analyze <file>` | Analyze URLs from file |
| `node agent.js check-reputation <url>` | Generate reputation lookup commands |
| `node agent.js trace-redirects <url>` | Generate redirect trace commands |

### Examples

```bash
# Decompose and analyze URL
node agent.js decompose "https://login.microsoft-verify.xyz/auth"

# Defang for incident report
node agent.js defang "https://evil.com/malware.exe"

# Batch analyze URL list from email campaign
node agent.js batch-analyze /tmp/extracted_urls.txt

# Check URL reputation across threat feeds
node agent.js check-reputation "https://suspicious-login.com"
```

## Reputation Services

| Service | API | Free Tier |
|---|---|---|
| VirusTotal | REST v3 | 4 requests/min |
| URLhaus | REST | Unlimited |
| PhishTank | REST | Unlimited with API key |
| Google Safe Browsing | REST v4 | 10,000 requests/day |

## URL Indicator Weights

| Indicator | Severity |
|---|---|
| IP address as hostname | High |
| Brand name in non-brand domain | High |
| Suspicious TLD (.xyz, .tk) | Medium |
| URL shortener | Medium |
| Unusual port | Medium |
| Excessive subdomains | Medium |
| Long random path | Low |
