Add Feature-Gate Phase 1: weighted credit cost + 4 orchestration/bulk endpoints

Endpoints (25 -> 29 MCP tools):
- GET /v1/audit/{domain} - full domain report + tech fingerprint + live headers
- GET /v1/threat-report/{ip} - Shodan + AbuseIPDB + ASN + enrichment
- POST /v1/cves/bulk - bulk CVE lookup (free 10, pro 50 per request)
- POST /v1/iocs/bulk - bulk IOC enrichment (free 10, pro 50 per request)

Rate limiting:
- consume_credits(cost, max) - atomic N-credit consume via BEGIN IMMEDIATE
- authenticate(request, endpoint, cost=1) - transparent per-endpoint cost
- COST_AUDIT=4, COST_THREAT_REPORT=4 (reflects upstream call count)
- X-RateLimit-Cost + X-RateLimit-Tier response headers

Security hardening:
- audit_domain: hard timeout guard (BULK_PER_DOMAIN_TIMEOUT) prevents worker hang
- audit_domain: sensitive header filter (strips Set-Cookie, Authorization,
  X-API-Key etc from live_headers to prevent target-site secret leakage)
- Rename TimeoutError -> FuturesTimeoutError alias for clarity

Frontend:
- Landing (EN + CN): 4 new endpoint cards + Credit Costs section + pricing update
- Playground: audit + threat_report cards (bulk excluded, single-input precedent)

Tests: 841 passed (+45 new - consume_credits atomicity, cost headers,
exhaustion gating, bulk size limits, audit/threat-report handlers, 4 MCP tools)

Author: UPinar

CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md — ContrastAPI
 
 ## Project
-Security intelligence API. 25 MCP tools, 35+ endpoints: CVE/EPSS/KEV, domain recon, IOC/threat intel, OSINT, code security.
+Security intelligence API. 29 MCP tools, 39+ endpoints: CVE/EPSS/KEV, domain recon, IOC/threat intel, OSINT, code security.
 Live: api.contrastcyber.com | GitHub: UPinar/contrastapi
 
 ## Quick Reference

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to ContrastAPI
 
-Thanks for your interest in contributing! ContrastAPI is a security intelligence API with 25 MCP tools and 35+ endpoints.
+Thanks for your interest in contributing! ContrastAPI is a security intelligence API with 29 MCP tools and 39+ endpoints.
 
 ## Quick Start
 
@@ -32,7 +32,7 @@ app/
 ├── codesec/           # Secret scanning, injection detection, headers
 │   ├── routes.py      # Code security endpoints
 │   └── utils.py       # Shared helpers (ReDoS-safe)
-├── mcp/               # MCP server (25 tools)
+├── mcp/               # MCP server (29 tools)
 │   └── server.py      # Tool definitions + handlers
 ├── templates/         # HTML templates (landing, docs, quickstart)
 ├── static/            # CSS, JS, images

README.md

@@ -7,20 +7,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Python 3.12](https://img.shields.io/badge/Python-3.12-blue.svg)](https://python.org)
 [![Tests](https://img.shields.io/badge/Tests-782_passing-brightgreen.svg)](https://github.com/UPinar/contrastapi/actions)
-[![MCP](https://img.shields.io/badge/MCP-25_tools-purple.svg)](https://modelcontextprotocol.io)
+[![MCP](https://img.shields.io/badge/MCP-29_tools-purple.svg)](https://modelcontextprotocol.io)
 [![VS Code](https://img.shields.io/badge/VS_Code-Marketplace-007ACC.svg)](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi)
 [![RapidAPI](https://img.shields.io/badge/RapidAPI-Available-blue.svg)](https://rapidapi.com/UPinar/api/contrastapi)
 [![npm](https://img.shields.io/npm/v/contrastapi.svg)](https://www.npmjs.com/package/contrastapi)
 
-**Security intelligence API and MCP server for AI agents.** 25 MCP tools / 35+ endpoints: CVE lookup with EPSS/KEV enrichment, domain reconnaissance, SSL analysis, IP reputation (AbuseIPDB, Shodan), IOC/malware lookup, exploit search, technology fingerprinting, email security, phone validation, and code security scanning. Free, no API key required.
+**Security intelligence API and MCP server for AI agents.** 29 MCP tools / 39+ endpoints: CVE lookup with EPSS/KEV enrichment, domain reconnaissance, SSL analysis, IP reputation (AbuseIPDB, Shodan), IOC/malware lookup, exploit search, technology fingerprinting, email security, phone validation, and code security scanning. Free, no API key required.
 
 **English** | [中文](README_CN.md)
 
 **Live:** [api.contrastcyber.com](https://api.contrastcyber.com) | **Quick Start:** [API](https://api.contrastcyber.com/quickstart) · [MCP](https://api.contrastcyber.com/mcp-setup) · [VS Code](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) | **Docs:** [Endpoints](#endpoints) | **Scanner:** [contrastcyber.com](https://contrastcyber.com) | **Blog:** [I Built 25 Security Tools That AI Agents Can Use](https://dev.to/contrastcyber/i-built-23-security-tools-that-ai-agents-can-use-4he7)
 
 ## Use with AI Agents
 
-**VS Code Extension:** Install [ContrastAPI](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) from the Marketplace — 25 security tools in your editor, no API key required.
+**VS Code Extension:** Install [ContrastAPI](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) from the Marketplace — 29 security tools in your editor, no API key required.
 
 **MCP Setup** for Claude Desktop, Cursor, VS Code, Windsurf: **[MCP Setup Guide](https://api.contrastcyber.com/mcp-setup)**
 
@@ -106,6 +106,8 @@ More examples: **[API Quick Start](https://api.contrastcyber.com/quickstart)** (
 
 ```
 GET  /v1/domain/{domain}       Full domain report (DNS + WHOIS + SSL + subs + WAF + reputation)
+GET  /v1/audit/{domain}        Comprehensive audit (full report + tech fingerprint + live headers)
+GET  /v1/threat-report/{ip}    Orchestrated IP threat report (Shodan + AbuseIPDB + ASN)
 GET  /v1/dns/{domain}          DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA)
 GET  /v1/whois/{domain}        WHOIS registration data
 GET  /v1/subdomains/{domain}   Subdomain enumeration (DNS brute + CT logs)
@@ -133,6 +135,7 @@ GET /v1/cves/recent?hours=24   Latest CVEs
 GET /v1/cves/kev               CISA exploited vulns
 GET /v1/epss/{cve_id}          Exploit probability
 GET /v1/exploit/{cve_id}       Public exploit search (GitHub Advisory + Shodan)
+POST /v1/cves/bulk             Bulk CVE lookup (10 free, 50 pro)
 ```
 
 ### Threat Intelligence
@@ -142,6 +145,7 @@ GET /v1/ioc/{indicator}        Unified IOC enrichment (IP, domain, URL, hash)
 GET /v1/hash/{hash}            Malware hash reputation (MalwareBazaar)
 GET /v1/password/{sha1}        Password breach check (HIBP, k-anonymity)
 GET /v1/phishing/{url}         Phishing/malware URL check (URLhaus)
+POST /v1/iocs/bulk             Bulk IOC enrichment (10 free, 50 pro)
 GET /v1/phone/{number}         Phone number OSINT (carrier, type, country)
 GET /v1/username/{username}    Username OSINT (16 platforms, account discovery)
 ```
@@ -162,6 +166,19 @@ POST /v1/check/dependencies    Check packages for known CVEs
 | Free | 100 req/hr | Not required |
 | Pro | 1,000 req/hr | [Get API Key](https://contrastcyber.com/pricing) |
 
+### Credit Costs
+
+Most endpoints consume **1 credit** per call. Aggregating endpoints that fan out to multiple upstream sources cost more:
+
+| Endpoint | Cost |
+|----------|------|
+| Most endpoints | 1 |
+| `GET /v1/audit/{domain}` | 4 |
+| `GET /v1/threat-report/{ip}` | 4 |
+| Bulk endpoints (`/v1/cves/bulk`, `/v1/iocs/bulk`) | N (one per item) |
+
+Every authenticated response includes an `X-RateLimit-Cost` header so you can track usage transparently alongside `X-RateLimit-Remaining`.
+
 ## Data Sources
 
 | Source | Records | Update |

README_CN.md

@@ -7,12 +7,12 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Python 3.12](https://img.shields.io/badge/Python-3.12-blue.svg)](https://python.org)
 [![Tests](https://img.shields.io/badge/Tests-782_passing-brightgreen.svg)](https://github.com/UPinar/contrastapi/actions)
-[![MCP](https://img.shields.io/badge/MCP-25_tools-purple.svg)](https://modelcontextprotocol.io)
+[![MCP](https://img.shields.io/badge/MCP-29_tools-purple.svg)](https://modelcontextprotocol.io)
 [![VS Code](https://img.shields.io/badge/VS_Code-Marketplace-007ACC.svg)](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi)
 [![RapidAPI](https://img.shields.io/badge/RapidAPI-Available-blue.svg)](https://rapidapi.com/UPinar/api/contrastapi)
 [![npm](https://img.shields.io/npm/v/contrastapi.svg)](https://www.npmjs.com/package/contrastapi)
 
-**安全情报 API 和 AI 智能体 MCP 服务器。** 25 个 MCP 工具 / 35+ 个端点：CVE 查询（含 EPSS/KEV 增强）、域名侦察、SSL 分析、IP 信誉（AbuseIPDB、Shodan）、IOC/恶意软件查询、漏洞利用搜索、技术指纹识别、电子邮件安全、电话号码验证和代码安全扫描。免费使用，无需 API 密钥。
+**安全情报 API 和 AI 智能体 MCP 服务器。** 29 个 MCP 工具 / 39+ 个端点：CVE 查询（含 EPSS/KEV 增强）、域名侦察、SSL 分析、IP 信誉（AbuseIPDB、Shodan）、IOC/恶意软件查询、漏洞利用搜索、技术指纹识别、电子邮件安全、电话号码验证和代码安全扫描。免费使用，无需 API 密钥。
 
 **在线服务：** [api.contrastcyber.com](https://api.contrastcyber.com) | **快速入门：** [API](https://api.contrastcyber.com/quickstart) · [MCP](https://api.contrastcyber.com/mcp-setup) · [VS Code](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) | **文档：** [接口列表](#接口列表) | **扫描器：** [contrastcyber.com](https://contrastcyber.com)
 
@@ -24,7 +24,7 @@
 
 ## 与 AI 智能体配合使用
 
-**VS Code 扩展：** 从 [Marketplace](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) 安装 ContrastAPI — 编辑器内 25 个安全工具，无需 API 密钥。
+**VS Code 扩展：** 从 [Marketplace](https://marketplace.visualstudio.com/items?itemName=ContrastAPI.contrastapi) 安装 ContrastAPI — 编辑器内 29 个安全工具，无需 API 密钥。
 
 **MCP 配置** 支持 Claude Desktop、Cursor、VS Code、Windsurf 等工具：**[MCP 配置指南](https://api.contrastcyber.com/mcp-setup)**
 
@@ -120,6 +120,8 @@ curl https://api.contrastcyber.com/v1/domain/example.com
 
 ```
 GET  /v1/domain/{domain}       完整域名报告（DNS + WHOIS + SSL + 子域名 + WAF + 信誉）
+GET  /v1/audit/{domain}        综合审计（完整报告 + 技术指纹 + 实时响应头）
+GET  /v1/threat-report/{ip}    编排式 IP 威胁报告（Shodan + AbuseIPDB + ASN）
 GET  /v1/dns/{domain}          DNS 记录（A、AAAA、MX、NS、TXT、CNAME、SOA）
 GET  /v1/whois/{domain}        WHOIS 注册信息
 GET  /v1/subdomains/{domain}   子域名枚举（DNS 爆破 + CT 日志）
@@ -147,6 +149,7 @@ GET /v1/cves/recent?hours=24   最新 CVE
 GET /v1/cves/kev               CISA 已利用漏洞
 GET /v1/epss/{cve_id}          漏洞利用概率
 GET /v1/exploit/{cve_id}       公开漏洞利用搜索（GitHub Advisory + Shodan）
+POST /v1/cves/bulk             批量 CVE 查询（免费 10 个，Pro 50 个）
 ```
 
 ### 威胁情报
@@ -156,6 +159,7 @@ GET /v1/ioc/{indicator}        统一 IOC 查询（IP、域名、URL、哈希）
 GET /v1/hash/{hash}            恶意软件哈希信誉（MalwareBazaar）
 GET /v1/password/{sha1}        密码泄露检查（HIBP，k-匿名）
 GET /v1/phishing/{url}         钓鱼/恶意 URL 检查（URLhaus）
+POST /v1/iocs/bulk             批量 IOC 富化（免费 10 个，Pro 50 个）
 GET /v1/phone/{number}         电话号码 OSINT（运营商、类型、国家）
 ```
 

app/auth.py

@@ -11,7 +11,7 @@
 from config import FREE_HOURLY_LIMIT, KEY_LENGTH, KEY_PREFIX, PRO_HOURLY_LIMIT
 from db import get_api_key, log_usage, touch_api_key
 from fastapi import HTTPException, Request
-from ratelimit import check_limit_with_count, get_reset_time
+from ratelimit import consume_credits, get_reset_time
 
 
 def generate_key() -> str:
@@ -41,7 +41,7 @@ def extract_key(request: Request) -> str | None:
     return None
 
 
-def authenticate(request: Request, endpoint: str) -> dict:
+def authenticate(request: Request, endpoint: str, cost: int = 1) -> dict:
     """Authenticate request. Returns auth context dict.
 
     For Pro keys: verifies key, checks hourly limit (1000/hr).
@@ -60,6 +60,7 @@ def authenticate(request: Request, endpoint: str) -> dict:
     raw_key = extract_key(request)
 
     localhost = client_ip in ("127.0.0.1", "::1")
+    request.state.ratelimit_cost = cost
 
     if raw_key:
         # Pro key authentication
@@ -74,7 +75,7 @@ def authenticate(request: Request, endpoint: str) -> dict:
 
         if not localhost:
             # Check Pro rate limit (sliding window)
-            allowed, remaining = check_limit_with_count("api", store_key, limit)
+            allowed, remaining = consume_credits("api", store_key, cost, limit)
             if not allowed:
                 _set_ratelimit_state(request, advertised_limit, 0, get_reset_time("api", store_key))
                 raise HTTPException(
@@ -88,6 +89,7 @@ def authenticate(request: Request, endpoint: str) -> dict:
         touch_api_key(kh)
         if not localhost:
             log_usage(client_ip, endpoint, key_hash=kh)
+        request.state.ratelimit_tier = "pro"
         return {"tier": "pro", "key_hash": kh, "client_ip": client_ip}
 
     # Keyless — IP rate limit (sliding window)
@@ -96,7 +98,7 @@ def authenticate(request: Request, endpoint: str) -> dict:
     store_key = f"free:{client_ip}"
 
     if not localhost:
-        allowed, remaining = check_limit_with_count("api", store_key, limit)
+        allowed, remaining = consume_credits("api", store_key, cost, limit)
         if not allowed:
             _set_ratelimit_state(request, advertised_limit, 0, get_reset_time("api", store_key))
             raise HTTPException(
@@ -110,4 +112,5 @@ def authenticate(request: Request, endpoint: str) -> dict:
 
     if not localhost:
         log_usage(client_ip, endpoint)
+    request.state.ratelimit_tier = "free"
     return {"tier": "free", "key_hash": None, "client_ip": client_ip}

app/config.py

@@ -36,6 +36,13 @@
 PRO_BULK_LIMIT = 50  # max domains per bulk request (pro)
 ENRICHMENT_DAILY_LIMIT = 10  # enriched scans per IP per day (protects external API quotas)
 
+# Endpoint credit costs — based on upstream API calls per request.
+# Default is 1 (single upstream). Orchestration endpoints cost more because
+# they aggregate multiple sources. Transparent pricing, surfaced via X-RateLimit-Cost header.
+COST_DEFAULT = 1
+COST_AUDIT = 4  # domain_report + live_headers + tech_detect + cache layer
+COST_THREAT_REPORT = 4  # ip_enrichment + abuseipdb + shodan + asn
+
 # API key
 KEY_PREFIX = "cc_"
 KEY_LENGTH = 48  # hex chars after prefix

app/cve/routes.py

@@ -6,7 +6,16 @@
 from auth import authenticate
 from db import get_cached_domain, get_cve, get_epss, get_kev_cves, get_recent_cves, save_cached_domain, search_cves
 from fastapi import APIRouter, HTTPException, Query, Request
-from schemas import CveKevResponse, CveRecentResponse, CveResponse, CveSearchResponse, EpssResponse, ExploitResponse
+from pydantic import BaseModel, Field
+from schemas import (
+    BulkCveResponse,
+    CveKevResponse,
+    CveRecentResponse,
+    CveResponse,
+    CveSearchResponse,
+    EpssResponse,
+    ExploitResponse,
+)
 from validation import is_valid_ip, validate_cve_id
 
 logger = logging.getLogger("contrastapi")
@@ -347,3 +356,88 @@ def exploit_lookup(cve_id: str, request: Request):
 
     save_cached_domain(cache_key, result)
     return {**result, "cached": False}
+
+
+# === Bulk CVE Lookup ===
+
+
+class _BulkCveRequest(BaseModel):
+    cve_ids: list[str] = Field(..., min_length=1, max_length=50)
+
+
+@router.post(
+    "/cves/bulk",
+    operation_id="bulk_cve_lookup",
+    response_model=BulkCveResponse,
+    response_model_exclude_none=True,
+)
+def bulk_cve_lookup(body: _BulkCveRequest, request: Request):
+    """Bulk CVE lookup — up to 10 CVEs (free) or 50 (pro). Each CVE counts as 1 request toward rate limit."""
+    import ratelimit
+    from auth import extract_key, hash_key
+    from config import FREE_BULK_LIMIT, FREE_HOURLY_LIMIT, PRO_BULK_LIMIT, PRO_HOURLY_LIMIT
+    from validation import get_client_ip
+
+    auth_ctx = authenticate(request, "/v1/cves/bulk")
+    client_ip = get_client_ip(request)
+
+    bulk_limit = PRO_BULK_LIMIT if auth_ctx["tier"] == "pro" else FREE_BULK_LIMIT
+
+    cve_ids = list(dict.fromkeys(c.strip().upper() for c in body.cve_ids if c.strip()))
+    count = len(cve_ids)
+
+    if count == 0:
+        raise HTTPException(status_code=400, detail="cve_ids must contain at least one valid CVE ID")
+    if count > bulk_limit:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Too many CVE IDs. Limit: {bulk_limit} (your tier: {auth_ctx['tier']})",
+        )
+
+    for cid in cve_ids:
+        if not validate_cve_id(cid):
+            raise HTTPException(status_code=400, detail=f"Invalid CVE ID format: {cid}")
+
+    raw_key = extract_key(request)
+    if raw_key:
+        store_key = f"pro:{hash_key(raw_key)}"
+        limit = PRO_HOURLY_LIMIT
+    else:
+        store_key = f"free:{client_ip}"
+        limit = FREE_HOURLY_LIMIT
+
+    if count > 1 and not ratelimit.consume_bulk("api", store_key, count - 1, limit):
+        raise HTTPException(
+            status_code=429,
+            detail=f"Insufficient rate limit quota for {count} CVE IDs.",
+        )
+
+    results = []
+    successful = 0
+    for cid in cve_ids:
+        try:
+            row = get_cve(cid)
+            if row is None:
+                results.append({"cve_id": cid, "status": "not_found", "cve": None, "error": f"CVE {cid} not found"})
+            else:
+                results.append({"cve_id": cid, "status": "ok", "cve": _format_cve(row), "error": None})
+                successful += 1
+        except Exception as e:
+            logger.warning("Bulk CVE lookup failed for %s: %s", cid, type(e).__name__)
+            results.append({"cve_id": cid, "status": "error", "cve": None, "error": "Lookup failed"})
+
+    failed = count - successful
+    if failed == 0:
+        summary = f"All {count} CVEs found"
+    elif successful == 0:
+        summary = f"No CVEs found in {count} lookups"
+    else:
+        summary = f"{successful}/{count} CVEs found, {failed} not found or failed"
+
+    return {
+        "results": results,
+        "total": count,
+        "successful": successful,
+        "failed": failed,
+        "summary": summary,
+    }