Integration Guide

Using Nerva with other security tools and in automated pipelines.

Port Scanner Integration

Naabu

Naabu is a fast port scanner from ProjectDiscovery.

# Basic integration
naabu -host example.com -silent | nerva

# With JSON output
naabu -host example.com -silent | nerva --json

# Scan subnet
naabu -host 10.0.0.0/24 -silent | nerva --json -o results.json

Masscan

Masscan is the fastest Internet port scanner.

# Masscan with nerva
masscan -p1-65535 10.0.0.0/24 --rate=10000 -oL - | \
  grep '^open' | \
  awk '{print $4":"$3}' | \
  nerva --json

Nmap

# Nmap greppable output to nerva
nmap -p- --open -oG - 10.0.0.1 | \
  grep 'Ports:' | \
  sed 's/.*Ports: //' | \
  tr ',' '\n' | \
  awk -F'/' '{print "10.0.0.1:"$1}' | \
  nerva --json

Data Processing

jq

Filter and transform JSON output:

# Get only SSH services
nerva -l targets.txt --json | jq 'select(.protocol=="ssh")'

# Extract IPs with HTTP
nerva -l targets.txt --json | jq -r 'select(.protocol=="http") | .ip'

# Count protocols
nerva -l targets.txt --json | jq -s 'group_by(.protocol) | map({protocol: .[0].protocol, count: length})'

CSV Processing

# Generate CSV
nerva -l targets.txt --csv -o results.csv

# Process with csvkit
csvgrep -c protocol -m ssh results.csv

CI/CD Integration

GitHub Actions

name: Security Scan

on:
  push:
    branches: [main]

jobs:
  fingerprint:
    runs-on: ubuntu-latest
    steps:
      - name: Install Nerva
        run: go install github.com/praetorian-inc/nerva/cmd/nerva@latest

      - name: Scan services
        run: |
          echo "app.example.com:80" > targets.txt
          echo "app.example.com:443" >> targets.txt
          nerva -l targets.txt --json | tee results.json

      - name: Check for unexpected services
        run: |
          UNEXPECTED=$(jq -r 'select(.protocol != "http" and .protocol != "https") | .protocol' results.json)
          if [ -n "$UNEXPECTED" ]; then
            echo "Unexpected services found: $UNEXPECTED"
            exit 1
          fi

GitLab CI

security-scan:
  image: golang:1.21
  script:
    - go install github.com/praetorian-inc/nerva/cmd/nerva@latest
    - nerva -l targets.txt --json -o fingerprints.json
  artifacts:
    paths:
      - fingerprints.json

Automation Scripts

Bash: Scan and Alert

#!/bin/bash

TARGETS="targets.txt"
EXPECTED_SERVICES="ssh http https"

nerva -l "$TARGETS" --json | while read -r line; do
    protocol=$(echo "$line" | jq -r '.protocol')
    host=$(echo "$line" | jq -r '.host')
    port=$(echo "$line" | jq -r '.port')
    
    if ! echo "$EXPECTED_SERVICES" | grep -qw "$protocol"; then
        echo "ALERT: Unexpected service $protocol on $host:$port"
    fi
done

Python: Process Results

import json
import subprocess

# Run nerva
result = subprocess.run(
    ["nerva", "-l", "targets.txt", "--json"],
    capture_output=True, text=True
)

# Process each line
for line in result.stdout.strip().split('\n'):
    if line:
        service = json.loads(line)
        print(f"{service['host']}:{service['port']} - {service['protocol']}")

Database Storage

PostgreSQL

CREATE TABLE fingerprints (
    id SERIAL PRIMARY KEY,
    host VARCHAR(255),
    ip VARCHAR(45),
    port INTEGER,
    protocol VARCHAR(50),
    transport VARCHAR(10),
    metadata JSONB,
    scanned_at TIMESTAMP DEFAULT NOW()
);

# Insert from nerva
nerva -l targets.txt --json | \
  jq -c '{host, ip, port, protocol, transport, metadata: .metadata}' | \
  while read line; do
    psql -c "INSERT INTO fingerprints (host, ip, port, protocol, transport, metadata) VALUES ($(echo $line | jq -r '@json'))"
  done

See Also

• CLI Reference
• Library Usage