<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: writing-network-protocol-templates
description: >-
  Write Nuclei network protocol templates for detecting vulnerabilities in
  TCP/UDP services. Covers raw TCP connections, TLS scanning, banner grabbing,
  service fingerprinting, and protocol-specific exploit detection.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - network
  - tcp
  - udp
  - protocol
  - service-detection
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1046"]
---

# Writing Network Protocol Templates

## Overview

Network protocol templates interact directly with TCP/UDP services, enabling
detection of vulnerabilities in non-HTTP services like databases, mail servers,
DNS, SSH, and custom protocols. These templates send raw bytes and match
response patterns to fingerprint services and detect known flaws.

Mode: `[MODE: RED]` — Network service vulnerability detection.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ with network protocol support | Required |
| Understanding of TCP/UDP protocols and hex encoding | Required |
| Target services accessible on the network | Required |

## Key Concepts

### Basic TCP Banner Grab

```yaml
id: ssh-server-detection

info:
  name: SSH Server Banner Detection
  author: nerf
  severity: info
  description: Identifies SSH server version from the connection banner.
  tags: ssh,network,detection
  metadata:
    max-request: 1

tcp:
  - inputs:
      - data: "\r\n"
    host:
      - "{{Hostname}}"
    port: 22
    read-size: 2048
    matchers:
      - type: regex
        regex:
          - 'SSH-2\.0-.*'
    extractors:
      - type: regex
        regex:
          - '(SSH-2\.0-[^\r\n]+)'
```

### TLS Certificate Analysis

```yaml
id: expired-tls-certificate

info:
  name: Expired TLS Certificate Detection
  author: nerf
  severity: medium
  description: |
    Detects TLS certificates that have expired, indicating potential
    security oversight and man-in-the-middle vulnerability.
  classification:
    cwe-id: CWE-295
  tags: tls,certificate,ssl,misconfig
  metadata:
    max-request: 1

ssl:
  - address: "{{Host}}:{{Port}}"
    matchers:
      - type: dsl
        dsl:
          - 'not_after < now'
    extractors:
      - type: dsl
        dsl:
          - 'subject_cn'
          - 'not_after'
          - 'issuer_org'
```

### MySQL Unauthorized Access

```yaml
id: mysql-unauthorized-access

info:
  name: MySQL Unauthorized Access
  author: nerf
  severity: critical
  description: |
    MySQL server allows connections without authentication credentials,
    exposing the database to unauthorized access and data exfiltration.
  classification:
    cwe-id: CWE-306
    cve-id: CVE-2012-2122
  tags: mysql,database,unauth,network
  metadata:
    max-request: 1

tcp:
  - inputs:
      - data: ""
    host:
      - "{{Hostname}}"
    port: 3306
    read-size: 1024
    matchers-condition: and
    matchers:
      - type: word
        words:
          - "mysql_native_password"
          - "caching_sha2_password"
        condition: or
      - type: word
        negative: true
        words:
          - "Access denied"
```

### DNS Zone Transfer Check

```yaml
id: dns-zone-transfer

info:
  name: DNS Zone Transfer (AXFR)
  author: nerf
  severity: high
  description: |
    DNS server permits zone transfer requests, leaking all DNS records
    for the domain including internal hostnames and IP addresses.
  classification:
    cwe-id: CWE-200
  tags: dns,zone-transfer,network,misconfig
  metadata:
    max-request: 1

dns:
  - name: "{{FQDN}}"
    type: AXFR
    matchers:
      - type: word
        words:
          - "IN\tA"
          - "IN\tMX"
          - "IN\tNS"
        condition: or
```

### SMTP Open Relay Detection

```yaml
id: smtp-open-relay

info:
  name: SMTP Open Relay Detection
  author: nerf
  severity: high
  description: |
    SMTP server configured as open relay allowing unauthenticated
    email sending from any source to any destination.
  classification:
    cwe-id: CWE-284
  tags: smtp,mail,open-relay,network,misconfig
  metadata:
    max-request: 1

tcp:
  - inputs:
      - data: "EHLO test.com\r\n"
        read: 1024
      - data: "MAIL FROM:<test@test.com>\r\n"
        read: 512
      - data: "RCPT TO:<test@external.com>\r\n"
        read: 512
      - data: "QUIT\r\n"
    host:
      - "{{Hostname}}"
    port: 25
    matchers-condition: and
    matchers:
      - type: word
        words:
          - "250"
      - type: word
        negative: true
        words:
          - "relay not permitted"
          - "Relay access denied"
          - "550"
```

## Workflow

### Step 1: Scan Network Services

```bash
node scripts/agent.js --action scan --target 192.168.1.10 \
  --template network-template.yaml --output /tmp/network-scan.json
```

### Step 2: Validate Template

```bash
node scripts/agent.js --action validate --template network-template.yaml
```

## Verification

- [ ] Template specifies correct protocol (tcp/ssl/dns)
- [ ] Port numbers match target service defaults
- [ ] `read-size` is appropriate for the expected response
- [ ] Hex-encoded data is correct for binary protocols
- [ ] Multi-step inputs handle protocol handshakes properly
- [ ] Tested against known-vulnerable service versions
- [ ] Negative matchers exclude common false positives

## References

- [Nuclei Network Protocol](https://docs.projectdiscovery.io/templates/protocols/network/basic-network)
- [Nuclei DNS Protocol](https://docs.projectdiscovery.io/templates/protocols/dns/basic-dns)
- [Nuclei SSL Protocol](https://docs.projectdiscovery.io/templates/protocols/ssl/basic-ssl)
