Skip to content

2 API access

2.1 Setup shell

Get API token in web interface on user profile page (User > Profile > API key > Generate). Setup shell environment for API access:

export APIKEY=""
export URL="https://sner-hub.flab.cesnet.cz"
alias snerapi='curl -s -H "X-API-KEY: $APIKEY"'

2.2 Single host query

Any service SHOULD NOT be visible from public Internet on core IdP or Directory controllers.

snerapi -XPOST \
  "$URL/api/v2/public/storage/host" \
  --json '{"address": "203.0.113.50"}' | jq

{
  "address": "203.0.113.50",
  "hostname": "dc1.example.org",
  "services": [
    {
      "info": "extrainfo: Anonymous bind OK",
      "notes": [
        {
          "data": "[\"cpe:/a:openldap:openldap\"]",
          "xtype": "cpe"
        },
        {
          "data": "{\"product\": \"OpenLDAP\", \"version\": \"2.2.X - 2.3.X\"}"
          "xtype": "nmap.banner_dict"
        }
      ],
      "port": 636,
      "proto": "tcp",
      "state": "open:syn-ack"
    }
  ]
}

2.3 Multiple hosts query

Check services exposed on department network segment.

snerapi -XPOST \
  "$URL/api/v2/public/storage/range" \
  --json '{"cidr": "203.0.113.0/26"}' | jq

[
  {
    "address": "203.0.113.3",
    "hostname": "dhcp-wk1.dept.example.org",
    "services": [
      {
        "info": "product: OpenSSH version: 8.4p1 Debian 5+deb11u1 extrainfo: protocol 2.0 ostype: Linux",
        "port": 443,
        "proto": "tcp",
        "state": "open:syn-ack"
      },
      {
        "port": 22,
        "proto": "tcp",
        "state": "open:syn-ack"
      }
    ]
  },
  {
    "address": "203.0.113.1",
    "hostname": "gw.dept.example.org",
    "services": [
      {
        "port": 179,
        "proto": "tcp",
        "state": "open:syn-ack"
      }
    ]
  }
]

2.4 Service list with filtering

Backup infrastructure SHOULD NOT be accessible from public Internet. For detailed information about filter syntax, please see the full specification.

snerapi -XPOST \
  "$URL/api/v2/public/storage/servicelist" \
  --json '{"filter": "Service.port==\"445\" AND Service.state ilike \"open:%\""}' | jq

[
  {
    "address": "2001:db8::71",
    "info": "product: Samba smbd version: 3.X - 4.X extrainfo: workgroup: UCN hostname: BACKUP-EXAMPLE",
    "port": 445,
    "proto": "tcp",
    "state": "open:syn-ack"
  }
]

2.5 List endpoints exposing specific product

List of popular database engine exposed to public Internet.

snerapi -XPOST \
  "$URL/api/v2/public/storage/versioninfo" \
  --json '{"product":"mariadb"}' | jq

[
  {
    "host_address": "203.0.113.30",
    "host_hostname": "serverx.example.org",
    "service_port": 3306,
    "service_proto": "tcp",
    "product": "mariadb",
    "version": "10.3.38",
    "extra": {
      "full_version": "5.5.5-10.3.38-MariaDB-1:10.3.38+maria~ubu2004-log"
    }
  }
]

2.6 Breakdown of exposed products on respective hosts

snerapi -XPOST \
  "$URL/api/v2/public/storage/versioninfo" | jq -s \
  '.[] | map({product,host_address}) | group_by(.product) | map({product: .[0].product, host_address: map(.host_address)})'

[
  {
    "product": "mariadb",
    "host_address": [
      "203.0.113.30"
    ]
  },
  {
    "product": "zookeeper",
    "host_address": [
      "203.0.113.30",
      "2001:db8::30"
    ]
  }
]

2.7 Vulnerabilities query with filtering

For detailed information about filter syntax, please see the full specification.

Fetch all vulnerabilities with somewhat significant severity:

snerapi -XPOST \
  "$URL/api/v2/public/storage/vulnlist" \
  --json '{"filter": "Vuln.severity not_in [\"info\", \"low\"]"}' | jq

[
  {
    "address": "203.0.113.30",
    "data": "{\"template-id\": \"ftp-anonymous-login\", ... }",
    "descr": "## Description\n\nAnonymous FTP access allows anyone to ...",
    "hostname": "example.scanned.test",
    "name": "FTP Anonymous Login",
    "port": 21,
    "proto": "tcp",
    "refs": [
      "URL-https://tools.ietf.org/html/rfc2577"
    ],
    "severity": "medium",
    "xtype": "nuclei.ftp-anonymous-login"
  }
]

Fetch all vulnerabilities on hosts in network X:

snerapi -XPOST \
  "$URL/api/v2/public/storage/vulnlist" \
  --json '{"filter": "Host.address inet_in \"203.0.113.0/26\""}' | jq

[
  {
    "address": "203.0.113.11",
    "data": "{\"template-id\": \"openssh-detect\", ...",
    "descr": "## Description\n\nOpenSSH service was detected...",
    "hostname": "example.scanned.test",
    "name": "OpenSSH Service - Detect",
    "port": 22,
    "proto": "tcp",
    "refs": [
      "URL-http://www.openwall.com/lists/oss-security/2016/08/01/2",
      "URL-http://www.openwall.com/lists/oss-security/2018/08/15/5",
      "URL-http://seclists.org/fulldisclosure/2016/Jul/51",
      "URL-https://nvd.nist.gov/vuln/detail/CVE-2016-6210",
      "URL-https://nvd.nist.gov/vuln/detail/CVE-2018-15473"
    ],
    "severity": "info",
    "via_target": "203.0.113.11",
    "xtype": "nuclei.openssh-detect"
  }
]