Use Cases

Use Cases

Asset Discovery in CI/CD

Scenario: Nightly GitHub Actions job that scans a staging subnet and fails the pipeline if unexpected hosts appear.

name: nightly-asset-discovery
on:
  schedule:
    - cron: '0 2 * * *'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install catnet
        run: |
          curl -sSL https://github.com/mendsec/catnet/releases/latest/download/catnet_Linux_x86_64.tar.gz | tar xz
          sudo mv catnet /usr/local/bin/

      - name: Scan staging subnet
        run: catnet scan 10.0.1.0/24 --quiet --format json -o scan.json

      - name: Check for unexpected hosts
        run: |
          EXPECTED="known-hosts.txt"
          cat scan.json | jq -r '.devices[] | select(.isAlive) | .ip' | sort > alive.txt
          comm -13 <(sort "$EXPECTED") alive.txt > unexpected.txt
          if [ -s unexpected.txt ]; then
            echo "UNEXPECTED HOSTS FOUND:"
            cat unexpected.txt
            exit 1
          fi

Red Team Reconnaissance

Scenario: Initial footprinting during an authorized engagement.

catnet scan 10.0.0.0/8 --no-ports -t 256 --quiet --format json -o hosts.json
catnet export hosts.json --format csv -o hosts.csv

Always ensure written authorization before scanning any network you do not own.

Integration with jq Pipelines

1. List alive hosts only:

catnet scan 10.0.0.0/24 --format json | jq '.devices[] | select(.isAlive)'

2. Filter by open port (e.g. all hosts with port 22 open):

catnet scan 10.0.0.0/24 --format json | jq '.devices[] | select(.openPorts | contains([22]))'

3. Count alive vs total:

catnet scan 10.0.0.0/24 --format json | jq '{total: .total, alive: .alive}'

4. Extract IPs as newline-separated list:

catnet scan 10.0.0.0/24 --format json | jq -r '.devices[] | select(.isAlive) | .ip'

5. Filter by hostname pattern:

catnet scan 10.0.0.0/24 --format json | jq '.devices[] | select(.hostname | test("prod\\."))'

Feeding Results into Elasticsearch

catnet scan 10.0.0.0/24 --format json | \
  curl -X POST "https://elasticsearch:9200/catnet-scans/_doc/" \
    -H "Content-Type: application/json" \
    -d @-

Scheduled Cron Scan with Change Detection

#!/bin/bash
TODAY="/tmp/scan-$(date +%Y%m%d).json"
YESTERDAY="/tmp/scan-$(date -d yesterday +%Y%m%d).json"

catnet scan 192.168.0.0/16 --quiet --format json -o "$TODAY"

if [ -f "$YESTERDAY" ]; then
  diff <(jq -r '.devices[] | select(.isAlive) | .ip' "$TODAY" | sort) \
       <(jq -r '.devices[] | select(.isAlive) | .ip' "$YESTERDAY" | sort)
fi

Scripting with --quiet and Exit Codes

catnet scan 192.168.1.1 --quiet --format json -o /tmp/out.json
if [ $? -eq 0 ]; then
  echo "Scan completed successfully"
elif [ $? -eq 130 ]; then
  echo "Scan was interrupted"
else
  echo "Scan failed" >&2
fi