Artifactory Integration Guide

Complete guide for integrating Socket Registry Firewall with JFrog Artifactory. Supports auto-discovery of repositories and all three deployment topologies.

Overview

Socket Registry Firewall integrates with Artifactory to protect package ingestion and distribution. The firewall can automatically discover and sync repository configurations from Artifactory, eliminating manual route configuration.

Supported Artifactory repository types:

• npm
• PyPI
• Maven
• Cargo (Bower format in Artifactory)
• RubyGems
• NuGet
• Go (Golang format in Artifactory)
• Conda (experimental)

Deployment Topologies

1. Upstream Deployment (Most Common)

Artifactory remote repositories pull packages through the firewall. Developers and CI use Artifactory directly.

Developer / CI  --->  Artifactory  --->  Socket Firewall  --->  Public Registry
                      (caching)                                   (npmjs.org, pypi.org)

Benefits:

• Single enforcement point
• No developer config changes needed
• Artifactory caches packages (most installs don't hit firewall)
• Centralized security for entire organization

Use when:

• You already have Artifactory deployed
• Developers are already configured to use Artifactory
• You want to protect package ingestion from public registries

See Upstream Deployment Setup →

2. Downstream Deployment

Developers and CI point at the firewall, which proxies to Artifactory (which may or may not have its own upstream).

Developer / CI  --->  Socket Firewall  --->  Artifactory  --->  Public/Internal Registry

Benefits:

• Protect developer workstations directly
• Works with Artifactory virtual repos or local repos
• Can layer on top of existing Artifactory setup

Use when:

• You want to protect specific teams or projects
• You have Artifactory hosting internal packages
• You want an additional security layer beyond Artifactory

See Downstream Deployment Setup →

3. Middle Deployment (Multi-Tier)

Firewall sits between two Artifactory instances (e.g., UAT → Production, Regional → Central).

Artifactory UAT     --->  Socket Firewall  --->  Artifactory Production
(Virtual Repo)                                    (Remote Repo)

Benefits:

• Scan packages flowing between internal registries
• Supports Artifactory virtual repos aggregating remote repos
• Protects multi-tier Artifactory topologies

Use when:

• You have multiple Artifactory instances (UAT/Prod, Regional/Central)
• Packages flow between Artifactory instances
• You need to scan internal package distribution

See Middle Deployment Setup →

Auto-Discovery Configuration

Socket Firewall can automatically discover all Artifactory remote repositories and create firewall routes without manual configuration.

Basic Auto-Discovery

path_routing:
  enabled: true
  domain: socket-firewall.company.com
  mode: artifactory
  
  private_registry:
    api_url: https://artifactory.company.com/artifactory
    api_key: your-artifactory-api-key  # Or use env var ARTIFACTORY_API_KEY
    interval: 5m  # Auto-sync every 5 minutes

Routes are discovered from Artifactory and updated automatically. No need to manually define each route!

Advanced Auto-Discovery

path_routing:
  enabled: true
  domain: socket-firewall.company.com
  mode: artifactory
  
  private_registry:
    # Authentication
    api_url: https://artifactory.company.com/artifactory
    api_key: your-artifactory-api-key
    # OR use basic auth:
    username: admin
    password: secret
    
    # Sync settings
    interval: 5m              # Sync interval (30s, 5m, 1h, etc.)
    default_registry: maven   # Fallback for unknown repo types
    
    # Repository filtering (regex patterns)
    include_pattern: "^(npm|pypi|maven)-.*"      # Only npm/pypi/maven repos
    exclude_pattern: "(tmp|test|snapshot)-.*"     # Exclude temp/test repos

How Auto-Discovery Works

1. Firewall calls Artifactory REST API: GET /api/repositories?type=REMOTE
2. Parses repository list and extracts:
   • Repository key (name)
   • Package type (npm, pypi, maven, etc.)
   • Remote URL
3. Creates firewall routes:
   • Path: /artifactory/api/{package-type}/{repo-key}/ (Artifactory-compatible path)
   • Upstream: Remote URL from repository config
   • Registry: Package type
4. Generates nginx configuration with discovered routes
5. Repeats on interval, adding/removing routes as repositories change

Environment Variables for Auto-Discovery

AUTO_DISCOVERY_MODE=artifactory
AUTO_DISCOVERY_API_URL=https://artifactory.company.com/artifactory
AUTO_DISCOVERY_API_KEY=your-api-key
AUTO_DISCOVERY_INTERVAL=5m
AUTO_DISCOVERY_DEFAULT_REGISTRY=maven
AUTO_DISCOVERY_INCLUDE_PATTERN=".*"
AUTO_DISCOVERY_EXCLUDE_PATTERN="(tmp|test)-.*"

Upstream Deployment Setup

Protect package ingestion by pointing Artifactory remote repos at the firewall.

Step 1: Deploy Socket Firewall

socket.yml:

socket:
  api_url: https://api.socket.dev

ports:
  http: 8080
  https: 8443

# Upstream mode - generates direct paths for registry-to-registry
config_mode: upstream

path_routing:
  enabled: true
  domain: socket-firewall.internal.company.com
  mode: artifactory  # Auto-discovery
  
  private_registry:
    api_url: https://artifactory.company.com/artifactory
    api_key: ${ARTIFACTORY_API_KEY}
    interval: 5m
    default_registry: maven
    exclude_pattern: "(tmp|test)-.*"

nginx:
  worker_processes: 4
  worker_connections: 8192

docker-compose.yml:

services:
  socket-firewall:
    image: socketdev/socket-registry-firewall:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SOCKET_SECURITY_API_TOKEN=${SOCKET_SECURITY_API_TOKEN}
      - ARTIFACTORY_API_KEY=${ARTIFACTORY_API_KEY}
    volumes:
      - ./socket.yml:/app/socket.yml:ro
      - ./ssl:/etc/nginx/ssl
    restart: unless-stopped

Start:

docker compose up -d
curl -k https://socket-firewall.internal.company.com:8443/health

Step 2: Configure Artifactory Remote Repositories

Point each Artifactory remote repository to the firewall instead of the public registry.

npm Remote Repository

1. Go to Administration → Artifactory → Repositories → Remote
2. Edit your npm remote repository (e.g., npm-remote)
3. Change URL from https://registry.npmjs.org to:

   https://socket-firewall.internal.company.com:8443/npm

4. If using self-signed certs:
   • Uncheck Verify SSL Certificate
   • Or add firewall's CA to Artifactory's trust store
5. Save

PyPI Remote Repository

1. Edit your PyPI remote repository (e.g., pypi-remote)
2. Change URL to:

   https://socket-firewall.internal.company.com:8443/pypi

3. Save

Maven Remote Repository

1. Edit your Maven remote repository (e.g., maven-central)
2. Change URL to:

   https://socket-firewall.internal.company.com:8443/maven

3. Under Advanced, set:
   • Store Artifacts Locally: Yes
   • Synchronize Properties: Whatever you prefer
4. Save

Other Ecosystems

Repeat for Cargo, RubyGems, NuGet, Go using the corresponding paths:

• Cargo: https://socket-firewall.internal.company.com:8443/cargo
• RubyGems: https://socket-firewall.internal.company.com:8443/rubygems
• NuGet: https://socket-firewall.internal.company.com:8443/nuget
• Go: https://socket-firewall.internal.company.com:8443/go

Step 3: Test

Test npm:

# Developers use Artifactory as normal
npm config set registry https://artifactory.company.com/artifactory/api/npm/npm-remote/
npm install lodash

# Check firewall logs
docker compose logs socket-firewall | grep lodash

Test PyPI:

pip config set global.index-url https://artifactory.company.com/artifactory/api/pypi/pypi-remote/simple
pip install requests

docker compose logs socket-firewall | grep requests

Step 4: Verify Auto-Discovery

Check that the firewall discovered your Artifactory repositories:

# View discovered routes
docker compose exec socket-firewall cat /app/discovered-routes.yml

# Check logs for discovery events
docker compose logs socket-firewall | grep "Discovered.*repositories"

Downstream Deployment Setup

Developers point at the firewall, which proxies to Artifactory.

socket.yml:

socket:
  api_url: https://api.socket.dev

ports:
  http: 8080
  https: 8443

# Default mode (downstream) - generates API paths for clients

path_routing:
  enabled: true
  domain: firewall.company.com
  
  routes:
    # Point to Artifactory virtual or remote repos
    - path: /npm
      upstream: https://artifactory.company.com/artifactory/api/npm/npm-virtual
      registry: npm
      
    - path: /pypi
      upstream: https://artifactory.company.com/artifactory/api/pypi/pypi-virtual
      registry: pypi

Client configuration:

# Developers point at firewall instead of Artifactory
npm config set registry https://firewall.company.com/npm/
pip config set global.index-url https://firewall.company.com/pypi/simple

Middle Deployment Setup

Firewall sits between two Artifactory instances. Supports virtual repos aggregating remote repos.

socket.yml:

socket:
  api_url: https://api.socket.dev

ports:
  http: 8080
  https: 8443

# Middle mode - generates both API and direct paths, no URL rewriting
config_mode: middle

path_routing:
  enabled: true
  domain: socket-firewall.internal.company.com
  
  routes:
    # UAT Artifactory virtual repo → Prod Artifactory remote repo
    - path: /pypi
      upstream: https://artifactory-prod.company.com/artifactory/api/pypi/pypi-remote
      registry: pypi
      mode: proxy  # IMPORTANT - passes URLs unchanged
      
    - path: /npm
      upstream: https://artifactory-prod.company.com/artifactory/api/npm/npm-remote
      registry: npm
      mode: proxy

UAT Artifactory Configuration:

1. Create virtual repository in UAT Artifactory
2. Add remote repository pointing to firewall:
   • Remote URL: https://socket-firewall.internal.company.com:8443/pypi
3. Virtual repo aggregates this remote

Why mode: proxy is required:

• Production Artifactory returns relative URLs like ../../packages/xyz/file.tar.gz
• mode: proxy passes these URLs through unchanged
• UAT Artifactory resolves relative URLs against its own base path
• mode: rewrite would break this by rewriting URLs to firewall paths

Troubleshooting

Artifactory Can't Reach Firewall

Symptom: Artifactory shows connection errors when fetching packages

Check:

# From Artifactory server, test connectivity
curl -k https://socket-firewall.internal.company.com:8443/health

# Check DNS resolution
nslookup socket-firewall.internal.company.com

# Check firewall from Artifactory
ping socket-firewall.internal.company.com

Solution:

• Verify DNS record points to firewall host
• Ensure firewall ports (8080/8443) are accessible from Artifactory
• Check firewall rules/security groups

SSL Certificate Errors

Symptom: Artifactory logs show SSL verification errors

Option 1 - Trust firewall cert in Artifactory:

# Copy firewall cert to Artifactory server
scp ssl/fullchain.pem artifactory-server:/tmp/socket-firewall.crt

# Add to Artifactory's Java trust store
keytool -import -alias socket-firewall \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -file /tmp/socket-firewall.crt \
  -storepass changeit

# Restart Artifactory

Option 2 - Disable SSL verification (testing only):

• In Artifactory remote repo settings, uncheck "Verify SSL Certificate"

Auto-Discovery Not Finding Repositories

Check Artifactory API access:

# Test API connectivity
curl -H "X-JFrog-Art-Api: your-api-key" \
  https://artifactory.company.com/artifactory/api/repositories?type=REMOTE

# Should return JSON list of repositories

Check firewall logs:

docker compose logs socket-firewall | grep -i discovery
docker compose logs socket-firewall | grep -i artifactory

Common issues:

• API key lacks permissions (needs "Read" on repositories)
• api_url incorrect (should end with /artifactory, not include /api)
• Network connectivity from firewall to Artifactory

Virtual Repo Doubled URLs

Symptom: Artifactory virtual repos return URLs like /artifactory/api/pypi/pypi-virtual/artifactory/api/pypi/pypi-remote/packages/...

Solution: Use config_mode: middle and mode: proxy:

config_mode: middle
path_routing:
  routes:
    - path: /pypi
      upstream: https://artifactory.company.com/artifactory/api/pypi/pypi-remote
      registry: pypi
      mode: proxy  # Critical - prevents URL rewriting

Package Downloads Failing

Check firewall is blocking correctly:

# Try to install known malicious package
npm install some-malicious-package

# Check firewall logs for block
docker compose logs socket-firewall | grep -i block

Check firewall is allowing correct packages:

# Install known safe package
npm install lodash

# Should succeed - check logs
docker compose logs socket-firewall | grep lodash

Best Practices

Repository Naming

Use consistent naming in Artifactory to simplify filtering:

• npm-public - Public npm registry
• npm-internal - Internal npm packages
• pypi-public - Public PyPI registry
• pypi-internal - Internal Python packages

Then use filters:

include_pattern: ".*-public"  # Only protect public-facing repos
exclude_pattern: ".*-internal"  # Don't scan internal packages

Caching Strategy

Artifactory caching + Firewall caching = Maximum efficiency:

1. Artifactory caches packages after first fetch
2. Firewall caches security results for 24h (default)
3. Subsequent installs hit Artifactory cache (never reach firewall)
4. New packages hit firewall once, then cached by both

Result: Minimal latency overhead after initial fetch

Monitoring

Monitor both Artifactory and Firewall:

Artifactory:

• Monitor remote repository health
• Check artifact download counts
• Review failed download requests

Firewall:

• Monitor block events (malicious packages)
• Check API error rates
• Review cache hit rates

Splunk integration (recommended):

splunk:
  enabled: true
  hec_url: https://splunk.company.com:8088/services/collector/event
  hec_token: ${SPLUNK_HEC_TOKEN}
  index: security
  source: socket-firewall-artifactory

High Availability

For production deployments:

1. Multiple firewall instances with shared Redis cache:

   YAML

   services:
     socket-firewall-1:
       # ... firewall config
     socket-firewall-2:
       # ... firewall config
     redis:
       # ... shared Redis

2. Load balancer in front of firewall instances

3. Artifactory remote repo points to load balancer VIP

Security Hardening

1. Use proper TLS certificates (not self-signed in production)
2. Rotate API keys regularly
3. Limit Artifactory API key permissions to read-only repositories
4. Use fail_open: false in production for maximum security
5. Monitor and alert on block events

Reference

Artifactory Remote Repository Configuration

Firewall Configuration Summary

Supported Package Types

Next Steps

• Upstream Deployment Guide - General upstream deployment details
• Configuration Reference - All configuration options
• Nexus Integration - Sonatype Nexus Repository Manager integration

Support

• GitHub Issues: https://github.com/SocketDev/socket-nginx-firewall/issues
• Documentation: https://docs.socket.dev
• Email: [email protected]