## Executive Summary REST API providing programmatic access to GitLab's malicious packages database for SSCS add-on customers. Enables security teams to validate dependencies in CI/CD pipelines, audit SBOMs, and receive real-time threat notifications. ## Problem & Solution **Problem**: Security teams need programmatic access to malicious package intelligence to integrate threat detection into CI/CD pipelines and security workflows. **Solution**: API endpoints for single package lookup, bulk SBOM validation, and webhook notifications for newly discovered threats. **Security Impact**: Reduces mean time to detection from days to minutes, enables automated blocking of malicious packages before production deployment. ## Success Metrics | Metric | Target | Timeline | |--------|--------|----------| | API response time (p95) | \<500ms | Ongoing | | SSCS customer adoption | 60% | 6 months post-GA | | API usage growth | 10K+ queries/day | 6 months | | SSCS add-on retention | \\>90% | 12 months | | Threat notification speed | \<5 minutes | Ongoing | ## User Stories 1. **Security Engineer**: Query package status before approval → API returns threat intelligence in \<500ms 2. **DevSecOps Lead**: Validate SBOM (up to 1,000 packages) → Results in \<5 seconds 3. **Security Engineer**: Subscribe to threat notifications via API → Webhooks delivered within 5 minutes of discovery, manage subscriptions through GET/DELETE endpoints ## API Endpoints ### 1. GET `/api/v4/security/malicious_packages/search` **Parameters**: * `name` (required): Package name * `ecosystem` (required): Package ecosystem identifier * `version` (optional): Specific version * `purl` (optional): Package URL format **Response** (200): `{ "malicious": true, "package": { "name": "lodash-extra", "ecosystem": "npm", "version": "4.17.0" }, "threat_intelligence": { "severity": "critical", "attack_vectors": ["typosquatting", "data_exfiltration"], "first_seen": "2025-01-15T10:30:00Z", "source": ["package_sentry", "github_advisory"], "cve_ids": ["CVE-2025-12345"] }, "remediation": { "description": "Remove immediately and audit for data exposure", "safe_alternative": "lodash@4.17.21" } }` **Errors**: 400 (invalid), 401 (auth), 403 (no SSCS subscription), 404 (not found), 429 (rate limit) ### 2. POST `/api/v4/security/malicious_packages/bulk_check` **Purpose**: Validate multiple packages in a single request **Request**: `{ "packages": [ {"name": "package-a", "ecosystem": "ecosystem1", "version": "1.0.0"}, {"name": "package-b", "ecosystem": "ecosystem2", "version": "2.3.1"} // ... up to 1,000 packages ] }` **Response**: Array of results matching search endpoint format ### 3. POST `/api/v4/security/malicious_packages/webhooks` **Purpose**: Create webhook subscription for malicious package notifications **Request**: `{ "url": "https://customer.com/webhook", "ecosystems": ["ecosystem1", "ecosystem2"], "severity_threshold": "high" }` **Response** (201 Created): `{ "id": "webhook_123", "url": "https://customer.com/webhook", "ecosystems": ["ecosystem1", "ecosystem2"], "severity_threshold": "high", "status": "active", "created_at": "2025-01-20T10:00:00Z" }` ### 4. GET `/api/v4/security/malicious_packages/webhooks` **Purpose**: List all webhook subscriptions for the authenticated user **Response** (200 OK): `{ "webhooks": [ { "id": "webhook_123", "url": "https://customer.com/webhook", "ecosystems": ["ecosystem1", "ecosystem2"], "severity_threshold": "high", "status": "active", "created_at": "2025-01-20T10:00:00Z" } ] }` ### 5. DELETE `/api/v4/security/malicious_packages/webhooks/:id` **Purpose**: Remove webhook subscription **Response** (204 No Content) ### Webhook Management **Configuration Location**: Customers manage webhooks entirely through API endpoints (POST to create, GET to list, DELETE to remove). **Future Consideration**: GitLab Settings → Webhooks UI for visual webhook management (out of scope for GA). ## Authentication **Token Generation**: * SSCS customers generate tokens via GitLab Settings → Access Tokens * Requires `read_security` scope * System validates SSCS add-on subscription before token creation * Tokens inherit SSCS entitlement and expire with the subscription * Token generation to support setting the expiration timeframe (no token should live forever) **Authorization**: * All requests require valid Personal Access Token or Project Access Token * API validates token + active SSCS subscription on each request * Available to Premium + SSCS and Ultimate + SSCS only ## Technical Requirements **Performance**: * Single query: p95 \<500ms * Bulk query (1,000 packages): p95 \<5s * Webhook delivery: \<5 minutes from threat discovery **Rate Limiting**: * 100 requests/min for search endpoint * 10 requests/min for bulk_check endpoint **Core Functionality**: * Package lookup by name, ecosystem, version, or Package URL (purl) * Bulk validation supporting up to 1,000 packages per request * Threat intelligence enrichment from multiple sources (Package Sentry, GitHub Advisory, OSV) * Webhook subscription and notification delivery with retry logic * Continuous synchronization with Vulnerability Research team's malicious packages database * Query audit logging for compliance and troubleshooting **Monitoring**: * API response time by endpoint * Error rate by status code * Database query performance * Webhook delivery success rate ## Deployment **GA Release (FY27 Q1)**: * SaaS (GitLab.com): Full availability for SSCS customers * Dedicated: Full availability * Self-Managed: GA+1 (requires data sync mechanism) **Configuration**: * `sscs_malicious_packages_api`: Enable/disable API access globally * `sscs_malicious_packages_webhooks`: Enable/disable webhook functionality * Rate limiting thresholds configurable per instance ## Out of Scope * UI-based portal for querying malicious packages database * **UI for webhook management** (Settings → Webhooks interface - webhooks managed via API only at GA) * Custom threat intelligence uploads * GraphQL API * Free tier access ## Open Questions * Minimum database coverage required for GA (target: 50K+ packages)? * [ ] Support both Personal and Project Access Tokens? * [ ] How to handle token generation UI for non-SSCS customers? * [ ] Self-Managed data sync mechanism for airgapped environments? * [ ] Data storage architecture: PostgreSQL vs. other options? Query audit log retention period? * [ ] Database synchronization frequency with Vulnerability Research team (every 15 minutes, hourly, real-time)? ## Risks & Mitigations | Risk | Impact | Mitigation | |------|--------|------------| | Incomplete threat database | High - False negatives | Define 50K+ package coverage target; transparency via metadata endpoint | | API performance degradation | High - Breaks CI/CD integration | Load test at 10x traffic; Redis caching; horizontal scaling | | False positives | Medium - Breaks legitimate builds | Multi-source validation; confidence scoring; appeals process | ## Dependencies * **Vulnerability Research team**: Database population, maintenance, and sync cadence * **Fulfillment team**: SSCS add-on license validation * **Distribution team**: Self-Managed data sync architecture * **Engineering**: Data storage architecture and retention policy definition