# DugganUSA Free Threat Intelligence Feed (STIX 2.1)

## 🌍 Open Source Threat Intelligence

**Free. Public. STIX 2.1 Compliant.**

Real-time threat intelligence from DugganUSA's production security operations. Updated continuously as our auto-blocking system identifies and blocks malicious actors.

---

## 🚀 Quick Start

### Recommended: STIX 2.1 V2 Endpoint

```bash
curl https://analytics.dugganusa.com/api/v1/stix-feed/v2
```

**Response:** Full STIX 2.1 Bundle with Indicators, SCOs, Malware SDOs, and Relationships. OpenCTI-ready.

### High Confidence Threats Only

```bash
curl "https://analytics.dugganusa.com/api/v1/stix-feed/v2?min_confidence=80"
```

### Filter by Country

```bash
curl "https://analytics.dugganusa.com/api/v1/stix-feed/v2?country=CN"
```

### Last 90 Days

```bash
curl "https://analytics.dugganusa.com/api/v1/stix-feed/v2?days=90"
```

### Legacy Endpoint (Still Supported)

```bash
curl https://analytics.dugganusa.com/api/v1/stix-feed
```

Simple Indicator-only format. No breaking changes planned - use whichever fits your needs.

---

## 📡 API Endpoints

### `GET /api/v1/stix-feed`

Returns STIX 2.1 Bundle with threat indicators.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `days` | integer | 30 | Filter to last N days |
| `min_confidence` | integer | 0 | Minimum confidence score (0-100) |
| `country` | string | - | Filter by 2-letter country code (e.g., CN, RU, US) |
| `format` | string | bundle | Output format: `bundle` or `indicators` |

**Response Format:** JSON (STIX 2.1 Bundle)

**Authentication:** None required (public feed)

**Rate Limits:** None

**Cache:** 5 minutes

---

### `GET /api/v1/stix-feed/info`

Returns feed metadata and usage information.

**Example:**
```bash
curl https://analytics.dugganusa.com/api/v1/stix-feed/info
```

---

### `GET /api/v1/stix-feed/schema`

Returns STIX 2.1 schema documentation and custom properties.

**Example:**
```bash
curl https://analytics.dugganusa.com/api/v1/stix-feed/schema
```

---

## 🆕 STIX 2.1 V2 Endpoint (OpenCTI-Ready)

### Why V2?

Community feedback (thanks Reddit!) identified that our V1 feed creates Indicators directly without the proper STIX 2.1 hierarchy. V2 addresses this:

| Feature | V1 | V2 |
|---------|----|----|
| Indicators | ✅ | ✅ |
| IPv4Address SCOs | ❌ | ✅ |
| Relationships | ❌ | ✅ |
| Malware SDOs | ❌ | ✅ |
| Cross-feed deduplication | ❌ | ✅ |
| OpenCTI graph traversal | ❌ | ✅ |

### `GET /api/v1/stix-feed/v2`

Returns STIX 2.1 Bundle with proper object hierarchy:

```
Bundle
├── Identity (DugganUSA LLC)
├── Attack Patterns (MITRE ATT&CK)
├── Malware SDOs (Stealc, LummaC2, Cobalt Strike, etc.)
├── IPv4Address SCOs (deterministic IDs)
├── Indicators (detection patterns)
└── Relationships
    ├── Indicator --"based-on"--> IPv4Address
    └── Indicator --"indicates"--> Malware
```

**Query Parameters:** Same as V1 (`days`, `min_confidence`, `country`, `limit`)

**Example:**
```bash
# Full V2 feed
curl https://analytics.dugganusa.com/api/v1/stix-feed/v2

# With filters
curl "https://analytics.dugganusa.com/api/v1/stix-feed/v2?min_confidence=70&limit=100"
```

**Response Headers:**
- `X-STIX-Feed-Version: 2.0`
- `X-Total-Objects`: Total objects in bundle
- `X-Total-Indicators`: Number of indicators
- `X-Total-SCOs`: Number of SCOs (IPv4Address objects)
- `X-Total-Relationships`: Number of relationship objects

### `GET /api/v1/stix-feed/v2/stats`

Returns V2 feed statistics and supported malware families.

**Example:**
```bash
curl https://analytics.dugganusa.com/api/v1/stix-feed/v2/stats
```

### Supported Malware Families

V2 includes Malware SDOs with MITRE ATT&CK mappings for:

| Family | Type | MITRE ID |
|--------|------|----------|
| Stealc | Infostealer | S1069 |
| LummaC2 | Infostealer | - |
| RedLine Stealer | Infostealer | S0943 |
| Rhadamanthys | Infostealer | - |
| Cobalt Strike | C2 Framework | S0154 |
| AsyncRAT | RAT | S0373 |
| Raccoon Stealer | Infostealer | S0650 |
| Vidar | Infostealer | S0538 |
| Amadey | Loader/Bot | - |
| Sliver | C2 Framework | - |

### V2 Migration Guide {#v2-migration}

**No action required!** V1 remains fully supported. V2 is additive.

**Recommended for:**
- OpenCTI users (proper graph structure)
- Multi-feed correlation (deterministic SCO IDs)
- Advanced threat hunting (relationship traversal)

**V1 still recommended for:**
- Simple IOC lists (firewall block lists)
- Legacy STIX parsers
- Minimal payload needs

### Monitoring Endpoint Status

Both endpoints return HTTP headers you can monitor programmatically:

| Header | V1 Value | V2 Value | Description |
|--------|----------|----------|-------------|
| `X-STIX-Feed-Version` | `1.0` | `2.0` | Feed format version |
| `X-Recommended-Endpoint` | `/api/v1/stix-feed/v2` | - | Suggested migration path |
| `X-Endpoint-Status` | `supported` | `recommended` | Endpoint lifecycle status |

**Status values:**
- `recommended` - Primary endpoint, actively developed
- `supported` - Fully functional, no breaking changes planned
- `deprecated` - Still works, migration advised (not currently used)

**Example: Check endpoint status**
```bash
curl -sI https://analytics.dugganusa.com/api/v1/stix-feed | grep X-Endpoint
# X-Endpoint-Status: supported
# X-Recommended-Endpoint: /api/v1/stix-feed/v2
```

We commit to publishing deprecation signals **at least 6 months** before any breaking changes.

---

## 📊 STIX Indicator Structure

Each indicator includes:

### Core STIX Properties

- **type:** `indicator`
- **spec_version:** `2.1`
- **id:** Unique identifier (`indicator--[uuid]`)
- **created/modified:** ISO 8601 timestamps
- **name:** Human-readable name (e.g., "Malicious IP: 1.2.3.4")
- **description:** Block reason and threat summary
- **indicator_types:** Array of types (`malicious-activity`, `anomalous-activity`, `malware-hosting`)
- **pattern:** STIX pattern (e.g., `[ipv4-addr:value = '1.2.3.4']`)
- **pattern_type:** `stix`
- **valid_from:** When threat was first observed
- **confidence:** 0-100 score based on multiple factors
- **labels:** Threat categorization
- **kill_chain_phases:** MITRE ATT&CK mapping (when available)

### Custom Properties (x_dugganusa_threat_intel)

- **abuse_score:** AbuseIPDB confidence score (0-100)
- **total_reports:** Community abuse reports
- **vt_detections:** VirusTotal malicious detections
- **threatfox_iocs:** ThreatFox IOC count
- **isp:** Internet Service Provider
- **usage_type:** IP classification (Hosting, ISP, etc.)
- **asn:** Autonomous System Number
- **asn_org:** ASN organization name
- **suspicious_isp:** Proxy/VPN/hosting flag
- **young_domain:** Domain age < 90 days
- **mitre_technique:** MITRE ATT&CK technique ID
- **auto_blocked:** Blocked by automated system
- **asshole_score:** Composite threat score

---

## 📖 Example Response

```json
{
  "type": "bundle",
  "id": "bundle--a1b2c3d4-...",
  "spec_version": "2.1",
  "objects": [
    {
      "type": "indicator",
      "spec_version": "2.1",
      "id": "indicator--e5f6g7h8-...",
      "created": "2025-11-13T12:00:00.000Z",
      "modified": "2025-11-13T12:00:00.000Z",
      "name": "Malicious IP: 1.2.3.4",
      "description": "AUTO-BLOCK: 95% abuse, 147 reports, VT:12",
      "indicator_types": ["malicious-activity"],
      "pattern": "[ipv4-addr:value = '1.2.3.4']",
      "pattern_type": "stix",
      "valid_from": "2025-11-13T12:00:00.000Z",
      "confidence": 95,
      "labels": ["malicious-ip", "CN", "hosting"],
      "external_references": [
        {
          "source_name": "DugganUSA Hall of Shame",
          "url": "https://www.dugganusa.com/hall-of-shame/1-2-3-4",
          "description": "Detailed threat actor profile"
        }
      ],
      "kill_chain_phases": [
        {
          "kill_chain_name": "mitre-attack",
          "phase_name": "command-and-control"
        }
      ],
      "x_dugganusa_threat_intel": {
        "abuse_score": 95,
        "total_reports": 147,
        "vt_detections": 12,
        "isp": "Digital Ocean",
        "asn": "14061",
        "auto_blocked": true,
        "asshole_score": 127.3
      }
    }
  ]
}
```

---

## 🔧 Integration Examples

### Python (STIX2 Library)

```python
import requests
from stix2 import parse

# Fetch feed
response = requests.get('https://analytics.dugganusa.com/api/v1/stix-feed?days=30')
bundle = parse(response.json())

# Process indicators
for obj in bundle.objects:
    if obj.type == 'indicator':
        print(f"Threat: {obj.name}")
        print(f"Confidence: {obj.confidence}%")
        print(f"Pattern: {obj.pattern}")
        print(f"Abuse Score: {obj.x_dugganusa_threat_intel['abuse_score']}")
```

### Bash + jq

```bash
# Get high confidence IPs
curl -s "https://analytics.dugganusa.com/api/v1/stix-feed?min_confidence=80" | \
  jq -r '.objects[] | select(.type=="indicator") | .pattern' | \
  grep -oP "\d+\.\d+\.\d+\.\d+" > blocked_ips.txt

# Count threats by country
curl -s "https://analytics.dugganusa.com/api/v1/stix-feed" | \
  jq -r '.objects[] | .labels[1]' | sort | uniq -c | sort -rn
```

### JavaScript

```javascript
// Fetch and process feed
const response = await fetch('https://analytics.dugganusa.com/api/v1/stix-feed');
const bundle = await response.json();

const indicators = bundle.objects.filter(obj => obj.type === 'indicator');

indicators.forEach(indicator => {
  const ip = indicator.pattern.match(/\d+\.\d+\.\d+\.\d+/)[0];
  const confidence = indicator.confidence;
  const country = indicator.labels[1];

  console.log(`${ip} - ${country} (${confidence}% confidence)`);
});
```

---

## 🎯 Use Cases

### SIEM Integration

Import indicators into your SIEM for correlation with internal logs:
- Splunk: Use HTTP Event Collector
- Elastic: Logstash HTTP input
- QRadar: Custom log source

### Firewall Rules

Auto-update firewall block lists:
```bash
# Daily cron job
0 0 * * * curl -s "https://analytics.dugganusa.com/api/v1/stix-feed?min_confidence=90" | \
  jq -r '.objects[] | .pattern' | grep -oP "\d+\.\d+\.\d+\.\d+" | \
  xargs -I {} iptables -A INPUT -s {} -j DROP
```

### Threat Hunting

Cross-reference IOCs with your network traffic:
```bash
# Check if your network contacted any malicious IPs
curl -s "https://analytics.dugganusa.com/api/v1/stix-feed" | \
  jq -r '.objects[] | .pattern' | grep -oP "\d+\.\d+\.\d+\.\d+" | \
  while read ip; do
    grep -q "$ip" /var/log/firewall.log && echo "ALERT: Connection to $ip detected"
  done
```

---

## 📈 What Makes This Feed Unique?

### Real Production Data
- Live from DugganUSA's security operations
- Continuously updated (not batch processed)
- Verified through multi-source enrichment

### Multi-Source Enrichment
- **AbuseIPDB:** Community abuse reports
- **VirusTotal:** Malware detection
- **ThreatFox:** C2 infrastructure tracking
- **Team Cymru:** ASN/BGP mapping
- **GreyNoise:** Benign noise filtering

### MITRE ATT&CK Mapping
- Automatic technique detection
- Kill chain phase classification
- Confidence scoring

### Zero Cost
- No API key required
- No rate limits
- No registration

---

## 🆓 Pricing

**Free Tier (Current):**
- ✅ Last 30 days of threats
- ✅ Unlimited requests
- ✅ Full STIX 2.1 schema
- ✅ Multi-source enrichment
- ✅ MITRE ATT&CK mapping

**Premium Tiers (Coming Soon):**
- **Conservative** ($245/month): 90-day retention + custom filters
- **Balanced** ($495/month): 180-day retention + TAXII server access
- **Aggressive** ($745/month): 365-day retention + private IOC submission + priority support

---

## 📜 License & Attribution

**License:** CC0-1.0 (Public Domain)

**Attribution (Optional but Appreciated):**
```
Threat intelligence provided by DugganUSA
https://analytics.dugganusa.com/api/v1/stix-feed
```

**Philosophy:** Democratic Sharing Law - we publish threat intel openly because shared intelligence improves faster than hoarded intelligence.

---

## 🛠️ Technical Details

### Update Frequency
- Real-time: Indicators added as threats are blocked
- Cache: 5-minute server-side cache
- Recommended polling: Every 15 minutes

### Data Retention
- Free tier: Last 30 days
- Premium tiers: Up to 365 days

### Performance
- Response time: < 2 seconds (typical)
- Bundle size: ~5-50 KB (compressed)
- Typical indicators: 50-200 per day

### Reliability
- Uptime: 99.9% target
- Backup: Azure Table Storage (globally replicated)
- Monitoring: 24/7 automated health checks

---

## 📞 Support & Contact

- **Email:** security@dugganusa.com
- **Documentation:** https://www.dugganusa.com/docs/stix-feed
- **GitHub:** https://github.com/dugganusa/enterprise-extraction-platform
- **Blog:** https://www.dugganusa.com/blog

**Issues?** Found a false positive? Email us with the IP and we'll investigate.

**Feature requests?** We're building the premium tiers based on user feedback. Tell us what you need.

---

## 🚀 What's Next?

### Coming Soon
- **TAXII Server:** Standard threat intel exchange protocol
- **Custom Filters:** Filter by ASN, ISP, usage type
- **Historical API:** Query specific date ranges
- **Bulk Export:** Download entire feed history
- **Webhooks:** Get notified of new threats

### Premium Features (Roadmap)
- **Private IOC Submission:** Submit your threat intel, get enriched feed
- **Custom Confidence Thresholds:** Set your own risk tolerance
- **Longer Retention:** 90/180/365-day feeds
- **Dedicated Support:** Direct Slack/Discord channel
- **SLA Guarantees:** 99.99% uptime commitment

---

## 🏆 Why We Built This

Most threat intelligence is hoarded behind paywalls or API keys. We believe shared intelligence improves faster than proprietary intelligence.

**Our Philosophy:**
- Zero marginal cost to share digital goods
- Community feedback improves detection
- Open data prevents vendor lock-in
- Transparency builds trust

**The Result:** A free, public STIX feed that competes with $5,000/month enterprise offerings.

---

**Last Updated:** December 30, 2025
**Feed Version:** 2.0.0 (V2 with SCOs + Relationships)
**STIX Version:** 2.1
**V1 Status:** Fully supported (no deprecation planned)