[RFC] gRPC protocol

[nukunga]

RFC: Native gRPC Protocol Support

Status

• Status: Draft — prepared for discussion
• Authors: @nukunga
• Created / Updated: 2026-06-21
• Discussion: projectdiscovery/discussions#6426
• Target: a future Nuclei v3 minor release (unary gRPC; streaming tracked separately)

This RFC originates from discussion #6426 and consolidates the design
ideas proposed there. It is intentionally self-contained: all supporting
research and citations are inlined (see Prior art), so the document
stands alone with no references to other files in the repository. See
References and attribution for who proposed what.

Abstract

Nuclei ships native protocol support for HTTP, DNS, network/TCP, SSL, WebSocket,
WHOIS, headless, file, code, and JavaScript, but it has no native gRPC
protocol. Authors who want to test gRPC endpoints today must shell out to
external tooling (grpcurl/evans) through the code protocol, which is gated,
requires template signing, and produces no first-class request/response model for
matchers and extractors.

This RFC proposes a native grpc protocol that lets template authors describe a
unary gRPC call declaratively, supplies the request message as JSON (marshaled to
Protocol Buffers via server reflection or an author-supplied schema), and exposes
the response to the existing matcher/extractor engine. The central design choice —
borrowed directly from grpcurl's model and from @matheusalbarello's proposal in
#6426 — is that template authors never touch the protobuf wire format.

Problem statement

• There is no way to author a gRPC check as a native Nuclei template. Protocol
  coverage stops at the transports listed above.
• The only workaround is the code protocol invoking grpcurl in a shell. This:
  • requires the -code flag and a signed template (code templates execute
    arbitrary local commands, so they are gated and must be signed by design — see
    Background);
  • depends on grpcurl being installed on the scanning host;
  • yields raw stdout, not a structured response, so matchers/extractors cannot
    address gRPC status codes, response fields, or trailers.
• Protocol Buffers require a schema to (de)serialize messages. A naive design would
  push .proto/protobuf concerns into YAML templates, which is unworkable for
  template authors. This is the core engineering challenge first called out by
  @zxelzy in #6426.

Goals

• Define a declarative grpc template block for unary RPC calls.
• Let authors express the request message as JSON; never require hand-written
  protobuf wire bytes.
• Resolve the message schema from one of three sources, defaulting to server
  reflection so the common case needs no .proto.
• Reuse the existing operators engine (matchers/extractors) unchanged by exposing
  the gRPC response as a DSL map.
• Integrate with multi-protocol templates, id-based request chaining, dynamic
  values, and the {{ }} variable/payload system.
• Follow the established protocol-implementation pattern so the addition is
  idiomatic and reviewable.

Non-goals

• Streaming RPCs (server-, client-, and bidirectional-streaming) are out of
  scope for v1. The syntax is designed to extend to streaming later (see
  Rollout plan).
• Non-protobuf gRPC codecs and full gRPC-Web transport. v1 targets native protobuf
  gRPC-over-HTTP/2; gRPC-Web endpoints are only detectable via the content_type part,
  and custom/non-protobuf codecs are unsupported.
• A general-purpose gRPC client library or evans-style interactive shell.
• Defining or shipping any .proto files; the protocol consumes schemas, it does
  not author them.
• Changing the template signing model, the -code gate, or matcher/extractor
  semantics beyond adding gRPC-specific response parts.
• Generating Go stubs from .proto at build time; all schema handling is runtime
  (reflection, runtime .proto compilation, or a precompiled descriptor set).
• Request clustering for gRPC in v1. Clustering
  (pkg/templates/cluster.go) only groups single HTTP/DNS/TLS requests, and gRPC
  requests are method-specific (distinct method + JSON body + descriptor source), so
  identical-request collisions are rare. Revisit in the streaming follow-up.
• Remote/registry descriptor fetch (e.g. Buf Schema Registry) in v1. Authors
  pre-build a FileDescriptorSet with buf build/protoc and reference it via
  descriptor-set; descriptor-set could later accept a URL. This keeps the
  "reproducible, offline runs" goal intact and avoids a new network-trust surface.

Terms

Server reflection — the optional gRPC service (grpc.reflection.v1.ServerReflection,
or the older v1alpha) a server may expose so clients can discover service,
method, and message descriptors at runtime. This is how grpcurl/evans operate
without a local .proto.

Descriptor — the protobuf schema (FileDescriptor/MethodDescriptor/
MessageDescriptor) needed to marshal a JSON request into a protobuf message and
unmarshal the response back to JSON.

Descriptor source — where Nuclei obtains descriptors: server reflection, a
.proto source file compiled at runtime, or a precompiled FileDescriptorSet.

Fully-qualified method — package.Service/Method, e.g.
helloworld.Greeter/SayHello.

Response part — a named key in the response DSL map that a matcher/extractor
can address via part: (e.g. body, status_code).

Background and current behavior

No native gRPC protocol today

Confirmed by @adilburaksen in #6426: the built-in protocols cover
http/tcp/dns/ssl/websocket/javascript (and file, whois, headless, code), but there
is no gRPC DSL. Each protocol implements the Request interface in
pkg/protocols/protocols.go (Compile, Requests, GetID, Match, Extract,
ExecuteWithResults, MakeResultEvent, MakeResultEventItem,
GetCompiledOperators, Type).

Current workaround: code protocol + grpcurl

Demonstrated by @matheusalbarello in #6426:

id: grpc-service-enum
info:
  name: gRPC service enumeration via grpcurl
  author: nukunga
  severity: info

code:
  - engine:
      - sh
    source: |
      grpcurl -plaintext {{Host}}:{{Port}} list
    matchers:
      - type: word
        words:
          - "grpc.reflection"

Run with nuclei -code -t grpc.yaml -u target:50051. As noted in the thread, -code
is gated behind a flag and requires template signing by design: unsigned code
templates are rejected during loading regardless of the flag, because the code
protocol executes arbitrary local commands (enforced in
pkg/catalog/loader/loader.go; the -code flag is registered in
cmd/nuclei/main.go). A network protocol such as gRPC does not execute local
code, so it should load unrestricted like HTTP/network (see
Security considerations).

Existing protocol architecture (grounding)

A new protocol is wired in by:

• adding a ProtocolType value and string mapping in
  pkg/templates/types/types.go;
• adding a request slice field on the Template struct and registering it through
  pkg/templates/templates.go (Type(), validateAllRequestIDs,
  hasMultipleRequests, addRequestsToQueue) and pkg/templates/compile.go
  (Requests(), updateRequestOptions, compileProtocolRequests), plus a
  Has*Request helper in pkg/templates/templates_utils.go;
• implementing the Request interface in a new pkg/protocols/grpc package.

The simplest existing protocol to model the new package on is whois
(pkg/protocols/whois/whois.go): it embeds operators.Operators inline, builds a
data map of response fields, and delegates matching to
protocols.MakeDefaultMatchFunc / MakeDefaultExtractFunc. The gRPC protocol
follows the same shape.

Proposal

Design principles

1. Idiomatic to Nuclei. grpc: is a list of requests; operators
   (matchers/extractors) are embedded inline; id enables request chaining;
   {{ }} variables and payloads work as in other protocols.
2. Reflection-first, three-source schema resolution. Default to server
   reflection so the common case needs no .proto; allow proto and
   descriptor-set as fallbacks for reflection-disabled targets. (Adapted from
   @zxelzy and @matheusalbarello, #6426; extended with descriptor-set.)
3. Author-facing JSON, never wire protobuf. Request bodies are JSON, marshaled
   to protobuf via the resolved descriptor; responses are marshaled back to JSON
   for matching. (Adopted from @matheusalbarello / the grpcurl model, #6426.)

Template syntax (the grpc block)

Canonical unary call using server reflection:

id: grpc-say-hello
info:
  name: gRPC SayHello probe
  author: nukunga
  severity: info

grpc:
  - host: "{{Hostname}}"                 # resolves to host:port, per the network convention
    method: "helloworld.Greeter/SayHello"
    reflection: true                     # default; obtain schema from server reflection
    request: |
      {"name": "nuclei"}                 # JSON -> protobuf via the resolved descriptor
    matchers:
      - type: word
        part: body                       # the response message, marshaled to JSON
        words:
          - "Hello nuclei"
      - type: status                     # gRPC status code; 0 = OK
        status:
          - 0
    matchers-condition: and

Schema acquisition model (reflection-first, three sources)

Exactly one descriptor source resolves per request. Reflection is the default
(the zero-config common case needs no .proto — this is the "reflection-first"
ergonomic). An explicitly set schema source overrides reflection, and if more
than one is set the precedence is descriptor-set > proto > reflection
(consistent with Precedence and resolution rules).
reflection is a tri-state *bool: omitted ⇒ default true, while an explicit
reflection: false disables it (and, with no proto/descriptor-set, is a
configuration error). This mirrors dns.Request.Recursion.

Source	Field(s)	Selected when
Descriptor set	descriptor-set	Explicitly set — a precompiled FileDescriptorSet (most reproducible); wins over the others
Runtime .proto	proto, import-paths	Explicitly set and no descriptor-set
Server reflection	reflection: true (default)	Default when no explicit source is given; target must expose the reflection service

If reflection is used but the target does not expose it, the request fails
with a clear, matchable error rather than silently degrading.

Request body model (JSON → protobuf)

• request is a JSON object string. After {{ }} evaluation it is unmarshaled
  into a dynamic protobuf message using the resolved input descriptor.
• JSON cleanly expresses protobuf constructs that a YAML map cannot (e.g.
  oneof, bytes as base64, well-known types such as google.protobuf.Timestamp).
  This is the main reason JSON is preferred over a YAML payload map (see
  Alternatives considered).
• request participates in payload fuzzing: {{placeholder}} tokens are filled
  from payloads with the chosen attack type, enabling per-field fuzzing.

Serialization (protojson) options

JSON ⇄ protobuf conversion uses protojson with fixed, documented options so
templates behave deterministically:

• Unmarshal (request): DiscardUnknown: false — an unknown JSON field is an error,
  which catches typos in template field names instead of silently dropping them.
• Marshal (response → body): UseProtoNames: true (emit snake_case proto field
  names so matchers stay stable across runs) and EmitUnpopulated: false (omit
  zero-value fields). Enums marshal to their string name, bytes as base64, and
  well-known types (Timestamp/Duration/Any) use their canonical JSON forms.

Response model and matcher/extractor parts

The response is exposed as a DSL map. Matchers/extractors select a key via part:
(default body). Extract delegates to protocols.MakeDefaultExtractFunc, but
Match is implemented directly (modeled on http/dns operators.go), because
the status matcher type is not handled by protocols.MakeDefaultMatchFunc —
that helper only covers word/regex/binary/size/dsl/xpath. The custom
Match adds a matchers.StatusMatcher case that calls matcher.MatchStatusCode
against the numeric gRPC code; all other matcher types delegate to the default func.
status_code is stored in the data map as an int (mirroring network's
getStatusCode), not a string. Copying whois verbatim — which has no status matcher —
would make type: status silently never match.

part key	Contents
body	Response message marshaled to JSON (default)
raw	Response message decoded schemalessly to field-number:wire-type:value when no descriptor resolves (field numbers/primitive values only; no field names)
raw_body	Undecoded response wire bytes (hex/base64) for byte-level matchers
status_code	Numeric gRPC status code (0 = OK … 16)
status	Symbolic gRPC status name (e.g. OK, PERMISSION_DENIED, UNAUTHENTICATED) for name-based matching
status_message	gRPC status message string
status_details / error_details	Rich error model: the grpc-status-details-bin trailer decoded to google.rpc.Status JSON (code + message + details Any list)
error	Error string when the call terminates non-OK (always populated on the non-OK / reflection-disabled path)
content_type	HTTP/2 content-type (application/grpc, application/grpc-web+proto, application/grpc-web-text, …) — lets a template positively flag a gRPC-Web endpoint
headers	Response/initial metadata
trailers	Trailing metadata
rtt	Round-trip time
host / method / request	Call context (target, method, JSON sent)

The numeric status_code is matched with the existing status matcher type (via the
custom Match above); the symbolic status part is for word/dsl matching by name.
Field-name matching on body requires a resolved descriptor; when none is available
(reflection off and no proto/descriptor-set), authors match field numbers and
primitive values on raw, or bytes on raw_body (see
Security considerations).

The default part is body. Because the shared MakeDefaultMatchFunc (and the extract
helper) default an empty part to response, not body, the data map exposes the
response JSON under both body and response, and the custom Match normalizes an
omitted part to body — so part: body and an omitted part stay equivalent.

Transport and metadata

• plaintext: true disables TLS. When absent, the connection uses TLS (gRPC's
  default); a tls block configures server-name (SNI), insecure, and mTLS
  cert/key/ca. (Adopted from @matheusalbarello, #6426.)
• metadata is a gRPC request-metadata multimap (map[string][]string; a key may
  repeat), with {{ }} support. Keys ending in -bin carry binary metadata as
  base64 (the gRPC convention). A scalar value is accepted as shorthand for a
  single-element list. This maps to google.golang.org/grpc/metadata.MD.
• timeout overrides the global per-request timeout.
• Connections may be pooled; the reuse cache key includes host, TLS-vs-plaintext
  mode, server-name, insecure, the client cert/key/ca identity, and any authority
  override — a connection is never reused across a differing TLS posture.

Field reference

Field	Type	Default	Meaning
id	string	—	Request id for multi-request chaining
host	string	{{Hostname}}	Dial target (host:port)
method	string	(required)	Fully-qualified package.Service/Method
request	string (JSON)	{}	Request message as JSON
reflection	bool	true (when omitted)	Resolve schema via server reflection; explicit false disables it (backed by a tri-state *bool internally — see Schema acquisition model)
proto	string	—	.proto source path (catalog-relative)
import-paths	[]string	—	Import search paths for proto
descriptor-set	string	—	Precompiled FileDescriptorSet path
plaintext	bool	false	Disable TLS
tls	block	—	server-name, insecure, mTLS cert/key/ca
metadata	map[string][]string	—	gRPC request metadata; a key may repeat (multimap). -bin-suffixed keys carry base64 binary metadata. A scalar is accepted as shorthand for a one-element list
timeout	int	global	Per-request timeout (seconds)
matchers / extractors	inline operators	—	Standard operators

Implementation sketch

Backing Go type and engine wiring — click to expand

Following the whois convention (pkg/protocols/whois/whois.go):

type Request struct {
    // operators are embedded inline, as in whois/network
    operators.Operators `yaml:",inline,omitempty" json:",inline,omitempty"`
    CompiledOperators   *operators.Operators `yaml:"-" json:"-"`

    ID     string `yaml:"id,omitempty" json:"id,omitempty" jsonschema:"title=id of the request"`
    Host   string `yaml:"host,omitempty" json:"host,omitempty" jsonschema:"title=grpc host to connect"`
    Method string `yaml:"method,omitempty" json:"method,omitempty" jsonschema:"title=fully-qualified service/method"`

    Request  string              `yaml:"request,omitempty" json:"request,omitempty" jsonschema:"title=json request body"`
    Metadata map[string][]string `yaml:"metadata,omitempty" json:"metadata,omitempty" jsonschema:"title=grpc request metadata (multimap; -bin keys are base64 binary)"`

    // descriptor source (resolves to exactly one; reflection is the default)
    // Reflection is a tri-state *bool (nil = omitted = default true), mirroring
    // dns.Request.Recursion (pkg/protocols/dns/dns.go) — a plain bool cannot tell
    // "omitted" from an explicit "reflection: false".
    Reflection    *bool    `yaml:"reflection,omitempty" json:"reflection,omitempty"`
    ProtoFile     string   `yaml:"proto,omitempty" json:"proto,omitempty"`
    ImportPaths   []string `yaml:"import-paths,omitempty" json:"import-paths,omitempty"`
    DescriptorSet string   `yaml:"descriptor-set,omitempty" json:"descriptor-set,omitempty"`

    Plaintext bool       `yaml:"plaintext,omitempty" json:"plaintext,omitempty"`
    TLSConfig *TLSConfig `yaml:"tls,omitempty" json:"tls,omitempty"`
    Timeout   int        `yaml:"timeout,omitempty" json:"timeout,omitempty"`

    // internal
    options    *protocols.ExecutorOptions
    descSource grpcurl.DescriptorSource     // resolved during Compile()
    generator  *generators.PayloadGenerator
}

Type() returns a new templateTypes.GRPCProtocol; Extract/MakeResultEvent
delegate to the protocols.MakeDefault* helpers, but Match is custom (see
Response model — the default match func
has no StatusMatcher case). Every field carries a yamldoc-go // description:
doc-comment (as whois.go does), since SYNTAX-REFERENCE/jsonschema generation reads
those comments, not the jsonschema: tags (those only feed the JSON-schema
reflector).

Engine integration points:

• pkg/templates/types/types.go — add GRPCProtocol to the enum and
  protocolMappings ("grpc").
• pkg/templates/templates.go — add RequestsGRPC []*grpc.Request field; handle
  it in Type(), validateAllRequestIDs, hasMultipleRequests,
  addRequestsToQueue; add the import.
• pkg/templates/templates_utils.go — add HasGRPCRequest.
• pkg/templates/compile.go — include in Requests(), updateRequestOptions,
  compileProtocolRequests.
• pkg/tmplexec/flow/flow_executor.go — add case templateTypes.GRPCProtocol to
  the NewFlowExecutor type switch. Its default branch returns
  "invalid request type", so an unregistered gRPC type hard-errors every
  flow/multi-protocol template, not only flow: ones.
• pkg/protocols/grpc/ — new package implementing the Request interface, modeled
  on pkg/protocols/whois for structure, but with a custom Match (like
  http/dns) and network-style payload/variable handling (whois has none).
• Clustering (pkg/templates/cluster.go) is a non-goal for v1.

Examples

(a) Reflection-disabled target — .proto fallback

grpc:
  - host: "{{Hostname}}"
    method: "helloworld.Greeter/SayHello"
    reflection: false
    proto: "protos/helloworld.proto"
    import-paths: ["protos"]
    request: '{"name":"nuclei"}'
    matchers:
      - type: dsl
        dsl:
          - "status_code == 0"
          - "contains(body, 'Hello')"
        condition: and

(b) TLS + metadata + status-based authorization check

grpc:
  - host: "{{Hostname}}"
    tls:
      server-name: "{{Host}}"
    method: "api.v1.AdminService/DeleteUser"
    metadata:
      authorization: "Bearer {{token}}"
    request: '{"id":"1"}'
    matchers:
      - type: status        # 0 (OK) here would indicate an authorization bypass
        status: [0]

(c) Message-field fuzzing via payloads

grpc:
  - host: "{{Hostname}}"
    method: "shop.Catalog/Search"
    request: |
      {"query": {{to_json(injection)}}}   # to_json adds quotes + JSON-escapes the payload
    payloads:
      injection:
        - "' OR '1'='1"
        - "../../etc/passwd"
    attack: clusterbomb
    matchers:
      - type: word
        part: body
        words:
          - "syntax error"
          - "SQLSTATE"

(d) Unary request chaining (id + extractor + metadata)

grpc:
  - id: login
    host: "{{Hostname}}"
    method: "auth.v1.AuthService/Login"
    request: |
      {"username": "admin", "password": "admin"}
    extractors:
      - type: json
        name: token
        internal: true        # passed to the next request, not emitted as output
        part: body
        json:
          - ".token"
  - host: "{{Hostname}}"
    method: "api.v1.AccountService/GetProfile"
    metadata:
      authorization: ["Bearer {{token}}"]
    request: "{}"
    matchers:
      - type: status
        status: [0]

Note: gRPC server reflection is itself a bidirectional-streaming RPC
(grpc.reflection.v1.ServerReflection/ServerReflectionInfo) and therefore cannot be
invoked as a unary template request in v1. Reflection is performed internally by
the descriptor resolver (see
Schema acquisition model);
a template-level reflection-enumeration primitive is deferred to the streaming
follow-up.

Precedence and resolution rules

1. method is required and must be fully qualified (package.Service/Method).
2. Descriptor source resolves to exactly one: if descriptor-set is set it wins;
   else if proto is set it is compiled at runtime; else reflection is used.
   reflection: false with neither proto nor descriptor-set is a
   configuration error.
3. Transport: plaintext: true and a tls block are mutually exclusive;
   specifying both is an error.
4. host defaults to {{Hostname}} (which carries host:port); an explicit
   host overrides it.
5. request defaults to an empty message ({}) when omitted.
6. The default matcher/extractor part is body.
7. A descriptor is required to marshal any non-empty request. A call with no
   resolved descriptor is possible only when the request is empty (an empty protobuf
   message is zero bytes regardless of its type); the response is then exposed only via
   the schemaless raw/raw_body parts. Schemaless generation of non-empty requests is
   out of scope (see Non-goals / Security considerations).

Author guidance

• Prefer reflection: true (the default) — it requires no local schema and mirrors
  how grpcurl/evans work.
• Use descriptor-set for reproducible, offline runs (build it with
  protoc --descriptor_set_out= or buf build -o image.binpb).
• Use proto + import-paths when you only have source .proto files.
• Use plaintext: true for development/cleartext endpoints; otherwise configure
  tls.
• For detection-only checks against reflection-disabled targets with no schema,
  match on status_code/error rather than body (see
  Security considerations for why body inspection
  needs a schema).
• On load-balanced targets the backend answering reflection may not be the one
  serving the method; prefer a pinned descriptor-set/proto when schema stability
  matters.

Validation and warning policy

Recommended warnings/errors at compile time:

• method missing or not fully qualified (package.Service/Method; no grpc://
  scheme).
• reflection: false with neither proto nor descriptor-set.
• Both plaintext: true and a tls block present.
• request is not valid JSON after {{ }} evaluation. {{ }}/payload substitution
  happens on the JSON string before unmarshaling, so values interpolated into JSON
  string positions must be JSON-escaped. The recommended policy is to wrap such
  values with the to_json DSL helper — e.g. {"q": {{to_json(injection)}}}, which
  emits a quoted, fully escaped JSON string — instead of a bare "{{injection}}", which
  breaks when a payload contains " or \. As a backstop the engine validates the
  post-interpolation request as JSON, and a permutation that yields invalid JSON fails
  with a matchable error rather than being silently skipped.
• proto/descriptor-set path not found in the catalog.
• Streaming method on a unary call. After the descriptor resolves, the method's
  client_streaming/server_streaming flags are checked; any streaming method is
  rejected in v1 with a clear, matchable error (unary-only — see
  Non-goals). Concretely:
  if md.IsStreamingClient() || md.IsStreamingServer() → error.

Resolved design questions (previously open):

• The numeric gRPC status reuses the existing status matcher type, handled by the
  protocol's custom Match (not a new grpc-status type); a symbolic status
  part is also exposed for name-based matching. See
  Response model.
• Request clustering is not supported in v1 (see Non-goals).

Future work: streaming (deferred)

Streaming RPCs are a v1 non-goal; adding them later touches Nuclei's
"one request → one/few response events" model, so the v1 syntax reserves these
extension points now to stay forward-compatible:

• stream: true and stream-mode: server|client|bidi opt a request into streaming.
• request accepts a JSON array of messages (client/bidi); a single object stays
  valid shorthand for unary — so today's request syntax does not have to change.
• New stream-only response parts: messages (array of decoded messages), message
  (current message), message_count, first_message, last_message. The final gRPC
  status still arrives in trailers/status_code, so a stream can have matching
  messages and a non-OK final status — the two must be evaluated independently.
• Bounds are mandatory: max-messages, max-duration, idle-timeout, max-bytes. A
  server stream may never end, and unbounded reads would stall scans or exhaust memory.
• A matcher scope rule (per-message vs whole-stream vs first/last) and a
  stop-on-match / half-close policy must be defined. These, plus bidi concurrency
  (concurrent send/receive loops, cancellation, deadlines), are why bidirectional
  streaming is expected to warrant its own RFC.

Staged rollout: v1 unary → v1.1 server-streaming (single request → many responses, the
lowest-complexity case) → client-streaming → bidirectional (separate RFC). Reflection
enumeration — itself a bidi-streaming API, handled internally today — could surface as a
built-in action rather than a raw streaming call, e.g. action: list-services /
describe, so authors never implement ServerReflectionInfo themselves. Streaming would
also need its own response parts (message / messages / message_count, and a
final_status_code distinct from unary status_code, since the final status arrives in
trailers) and a matcher scope (per-message / aggregate / until-match) with
dedicated bounds (max-messages, max-duration, idle-timeout, first-message-timeout).

Security considerations

• No -grpc gate and no mandatory signing. The -code flag and template
  signing exist specifically because the code protocol executes arbitrary local
  commands (enforced in pkg/catalog/loader/loader.go). gRPC only makes outbound
  network calls, like HTTP and network; it should load unrestricted and adopt those
  protocols' posture, not the code protocol's.

• Loading a schema executes no code. Runtime .proto compilation
  (protocompile) only parses source — it does not invoke protoc, plugins, or
  codegen — and a descriptor-set is inert data. This reinforces why no signing is
  needed: unlike code, no author-supplied input is executed.

• Validate schema-file paths. proto, import-paths, descriptor-set, and the
  mTLS cert/key/ca paths are catalog-relative and MUST be confined to the
  template/catalog root — reuse Options.GetValidAbsPath / IsPathWithinDirectory
  (pkg/utils/filepath), which canonicalizes symlinks and rejects ..-escapes;
  absolute paths and traversal outside the root are refused. A schema file is not
  executed, but it changes how requests/responses are (de)serialized, so when a
  signed template references an external schema file that file must fall inside the
  template's signing/provenance scope — otherwise a verified template could be silently
  re-pointed at a different schema.

• Treat reflection/descriptor input as untrusted. Descriptors returned by a
  target's reflection service (and author-supplied .proto/descriptor-set) are
  attacker- or third-party-controlled, so the resolver MUST enforce concrete bounds
  rather than parsing unboundedly:

  • a reflection timeout, plus max descriptor response bytes, max descriptor
    files, max symbols, and max message nesting depth;
  • a max receive message size and a decompression limit on responses;
  • a max response-JSON size and max metadata size exposed to operators.

  Resolved descriptors are cached per host+method within a scan (with TTL/eviction) to
  avoid repeated reflection round-trips.

• Reflection is an information-exposure surface. Many production servers disable
  it on purpose. The protocol must support reflection-disabled targets via
  proto/descriptor-set and fail with a clear, matchable error — never a silent
  skip that reads as "not vulnerable."

• No schema ⇒ field-number matching only. The protobuf wire format carries field
  numbers and wire types but not field names. Without a descriptor, field-name
  matchers on body cannot be satisfied, but the response is still decoded
  schemalessly (field numbers and approximate values, à la protoc --decode_raw) and
  exposed via the raw / raw_body parts (see
  Response model), so authors can still
  match field numbers and primitive values. Schemaless request generation remains
  out of scope.

• TLS verification is on by default. Certificates are verified unless the author
  sets tls.insecure: true explicitly, and plaintext: true must be an explicit
  opt-in for cleartext targets. mTLS material (tls.cert/tls.key) and metadata
  secrets (e.g. authorization) support {{ }} interpolation so they are not
  hard-coded in shared templates.

• Destination ownership. A request dials the author-declared host (default
  {{Hostname}} from scan input), consistent with other protocols; the same
  target-resolution and SSRF considerations as network/HTTP apply.

Backward compatibility

• Purely additive: a new protocol type and a new grpc template block. No existing
  template changes behavior.
• The code + grpcurl workaround continues to work for authors who prefer it.
• No changes to signing, the -code gate, or operator semantics; only new
  gRPC-specific response parts are introduced.

Alternatives considered

A. Keep using the code + grpcurl workaround

Proposed as the interim approach by @matheusalbarello (#6426). Rejected as the
end state: requires the -code gate and signed templates, depends on grpcurl
on the host, and exposes only unstructured stdout to operators.

B. service: + method: split with a YAML payload: map

Proposed by @zxelzy (#6426):

grpc:
  - service: "helloworld.Greeter"
    method: "SayHello"
    payload:
      name: "Nuclei"

Partially adopted (reflection-first and the pkg/protocols/grpc integration come
from this proposal), but the single method: service/method string is preferred
because it matches reflection lookup keys and reduces author error, and a JSON
request body is preferred over a YAML payload map because YAML cannot cleanly
express oneof, bytes, or well-known types.

C. Protobuf wire bytes directly in YAML

Rejected: unworkable for authors and brittle across schema changes; defeats the
purpose of a declarative template.

D. Reimplement HTTP/2 + protobuf in the JavaScript runtime

Considered (the JS net library exists). Rejected: gRPC is HTTP/2 + protobuf, and
reimplementing framing and protobuf by hand in JS is error-prone and slow. As
@matheusalbarello noted (#6426), shelling out or building a native protocol is
the pragmatic path.

Prior art

How existing DAST and API-security tools test gRPC — and how they handle the
schema problem when no .proto is available — was surveyed with two independent
research passes that were then cross-verified: one using adversarial multi-vote
verification (high bar, narrow confirmed set), the other citation-backed breadth
across more vendors (wider coverage, lower per-claim assurance). The core
reflection-first conclusions below were confirmed by both passes; the broader
commercial-vendor inventory rests on the single citation-backed pass and is flagged
where confidence is lower. All sources are listed at the end of this section.

The landscape splits into two camps:

• Reflection-first tooling — grpcurl,
  Evans, and
  StackHawk HawkScan
  query gRPC server reflection at runtime and fall back to author-supplied
  .proto/FileDescriptorSet. HawkScan is the closest DAST precedent (reflection by
  default, descriptor-set fallback; its gRPC support is Beta); grpcurl is the
  reference UX for the JSON-through-descriptor model this RFC adopts. This is exactly
  the table-stakes pattern proposed here. Note that server reflection is frequently
  disabled in production for security, so on real targets the .proto/descriptor-set
  fallback is often the de-facto primary path, not an afterthought (see
  Security considerations).
• Schemaless / blackbox tooling — the Burp Suite ecosystem
  (blackboxprotobuf/bbpb,
  grpc-pentest-suite,
  bRPC-Web) and the
  OWASP ZAP gRPC add-on
  decode the protobuf wire format with no schema, emitting field-number-keyed output
  (field names are absent from the wire). As of late 2025 these are scoped almost
  entirely to gRPC-Web, not native gRPC-over-HTTP/2: no native-gRPC Burp extension
  was found (Burp supports the HTTP/2 transport, but appears to lack native gRPC
  message decoding).

Most commercial API-security platforms do not offer first-class gRPC DAST:
Bright, APIsec, Rapid7 InsightAppSec, and 42Crunch take contract/schema inputs
(OpenAPI/Swagger/Postman/WSDL/GraphQL, varying by tool) rather than gRPC descriptors;
Wallarm surfaces gRPC in runtime traffic discovery rather than schema-based testing.
(Akto's own docs additionally claim gRPC security testing and fuzzing, but that is an
unverified vendor claim.) Dedicated fuzzers
(Viasat gRPC-Fuzzer, Microsoft RESTler,
boofuzz) are either .proto-required-and-unary-only or not gRPC-aware.

Where this design sits relative to the surveyed state of the art:

	Capability	Status here
Table-stakes	Reflection + .proto/descriptor-set + JSON-body marshaling	✅ Core of this RFC (matches StackHawk/grpcurl/Evans)
Differentiator	First-class gRPC in an open YAML-template scanner	✅ No surveyed tool offers this
Partial	Schemaless decode when reflection is off and no schema supplied	◐ Response-side via the raw part (field numbers/values); request-side schemaless out of scope
Partial	gRPC-Web (browser-facing)	◐ Detectable via the content_type part; full gRPC-Web transport deferred (native gRPC-over-HTTP/2 only in v1)
Gap	Streaming RPCs (client/server/bidi)	✗ v1 non-goal; only Evans does all three today

The survey also confirms the table-stakes pattern is buildable with mature Go
libraries — google.golang.org/protobuf/dynamicpb + protojson with a reflection
client (the older jhump/protoreflect/dynamic is now deprecated in favor of these),
which is why the Dependencies below use google.golang.org/protobuf's
dynamicpb/protojson. These gaps are typical (no surveyed tool combines
reflection-first, descriptor upload, schemaless fallback, gRPC-Web, and full
streaming), but they are real versus the union of the state of the art: the streaming
gap is tracked in the Rollout plan; schemaless decode is addressed
response-side via the raw part, and gRPC-Web is detectable via content_type with
full transport support deferred.

Sources (prior-art survey):

• grpcurl — https://github.com/fullstorydev/grpcurl
• Evans — https://github.com/ktr0731/evans
• StackHawk HawkScan (gRPC) — https://docs.stackhawk.com/hawkscan/configuration/grpc-configuration/ ; https://www.stackhawk.com/blog/grpc-security-how-stackhawk-scans-grpc-services/
• OWASP ZAP gRPC add-on — https://www.zaproxy.org/docs/desktop/addons/grpc-support/ ; https://www.zaproxy.org/blog/2024-05-21-introducing-the-grpc-addon/
• blackboxprotobuf (NCC Group) — https://github.com/nccgroup/blackboxprotobuf ; bbpb-grpc-web — https://github.com/Hamz-a/bbpb-grpc-web
• grpc-pentest-suite / gRPC-Web Coder — https://github.com/nxenon/grpc-pentest-suite ; https://portswigger.net/bappstore/63b92be302fa4521bf18d74b3adbbc00
• bRPC-Web (Compass Security) — https://github.com/CompassSecurity/bRPC-Web ; https://blog.compass-security.com/2025/10/brpc-web-a-burp-suite-extension-for-grpc-web/
• PortSwigger Protobuf Decoder — https://portswigger.net/bappstore/bd8c70d3f1b74679b2a9fed03d36e81a
• Viasat gRPC-Fuzzer — https://github.com/Viasat/gRPC-Fuzzer
• jhump/protoreflect (deprecated; prefer std dynamicpb/protojson) — https://github.com/jhump/protoreflect
• gRPC/gRPC-Web security assessment background — https://bhamza.me/blogpost/2024/03/04/Security-assessing-grpc-and-grpcweb-services.html

Dependencies

A native implementation introduces new direct dependencies (none of these are
currently direct deps; google.golang.org/protobuf is present only as an indirect
dependency, and HTTP/2 is already available via golang.org/x/net):

• google.golang.org/grpc — the gRPC client.
• google.golang.org/protobuf — descriptors, dynamicpb, protojson.
• A reflection/descriptor toolkit. github.com/fullstorydev/grpcurl already
  unifies the three descriptor sources (DescriptorSourceFromServer,
  DescriptorSourceFromProtoFiles, DescriptorSourceFromProtoSets) plus
  InvokeRPC; for runtime .proto compilation, github.com/bufbuild/protocompile.

Rollout plan

1. Land this RFC, gather maintainer feedback on syntax and the descriptor-source
   model.
2. Implement the pkg/protocols/grpc package (unary) modeled on pkg/protocols/whois,
   plus the engine integration points.
3. Wire reflection as the default descriptor source; add proto and
   descriptor-set resolvers.
4. Add documentation and example templates; add integration tests under
   internal/tests/integration with a local gRPC test server.
5. Add // description: doc-comments to every grpc field, then run
   make docs && make syntax-docs and commit the regenerated
   pkg/templates/templates_doc.go, SYNTAX-REFERENCE.md, and
   nuclei-jsonschema.json in the same PR (generation reads the doc-comments, not the
   jsonschema: tags).
6. Evaluate streaming RPC support and request clustering in a follow-up RFC.

Acceptance criteria

• An author can run a unary gRPC check against a reflection-enabled target with no
  local .proto.
• The same check works against a reflection-disabled target using proto or
  descriptor-set.
• Matchers/extractors can address body, status_code, status_message, and
  metadata.
• payloads fuzz request message fields; id chaining passes extracted values
  between gRPC requests.
• gRPC templates load without -code and without signing.
• Existing templates are unaffected.

Integration tests (against a local gRPC test server) should cover at least:

• unary call against a reflection-enabled target;
• reflection-disabled target resolved via proto, and via descriptor-set;
• descriptor-set > proto > reflection precedence when several are set;
• reflection: false with no schema source → configuration error;
• invalid method format; streaming method rejected (unary-only);
• plaintext: true + tls block → conflict error;
• invalid JSON after payload substitution → matchable error;
• status matcher on the numeric code; extractor default part; body/response
  alias equivalence;
• status_details / trailers (rich error) decode;
• metadata injection (including a -bin key) and TLS server-name handling;
• schema-file path traversal rejected.

References and attribution

Originating discussion:
Is gRPC implement in nuclei engine? — projectdiscovery/discussions#6426

Contributor attribution (from #6426):

Design element	Source	How it is used here
Original request + intent to build native gRPC	@nukunga (OP, 2025-08-26)	Motivates this RFC
"No native gRPC; pkg/protocols Protocol/Request interfaces; code protocol as interim"	@adilburaksen (2026-05-11)	Background and current-behavior inventory
pkg/protocols/grpc package + RequestsGRPC on the Template struct; reflection-vs-.proto as the core serialization question; "open an RFC first"	@zxelzy (2026-05-24)	Integration points; descriptor-source model; this RFC exists per that advice
JSON request body marshaled via reflection (the grpcurl model); single service/method; plaintext/tls; optional proto; code+grpcurl interim template	@matheusalbarello (2026-06-01)	Core request/response model, transport fields, and the interim workaround in Background

Extensions beyond the discussion (added in this RFC): descriptor-set as a
third schema source; explicit response-part model (status_code, status_message,
trailers, metadata, rtt); metadata request headers; payloads-based field
fuzzing; id-based request chaining; security rationale for no gate/signing; the
no-schema raw-decode limitation; the engine-integration checklist.

Codebase references (current dev):
pkg/protocols/protocols.go (Request interface), pkg/protocols/whois/whois.go
(skeleton), pkg/templates/types/types.go (ProtocolType), pkg/templates/templates.go,
pkg/templates/compile.go, pkg/templates/templates_utils.go (registration),
pkg/catalog/loader/loader.go and cmd/nuclei/main.go (code gating/signing scope).

External references:
github.com/fullstorydev/grpcurl, github.com/bufbuild/protocompile,
google.golang.org/grpc, google.golang.org/protobuf (dynamicpb, protojson,
reflect/protodesc).

[dwisiswant0]

I'm not completely convinced that we should frame this as native grpc support specifically.

gRPC is only one RPC framework (by Google), I mean if we build the architecture around gRPC as a special-case protocol, we may end up solving only that one case while leaving the broader class of RPC-style targets untouched.

I see the problem not as "nuclei cannot speak gRPC", but "nuclei has no good model for testing RPC-style services" because gRPC is one case of that. XML-RPC, JSON-RPC, Apache Thrift, Java RMI, .NET Remoting, etc., are differ in transport/schema/encoding, but from my PoV they are all variations of the same basic shape.

So I would rather see the design start from that model and ask whether we should leave room for those other protocols to fit into the same conceptual model, rather than introducing a gRPC-specific shape that later becomes hard to generalize, and then someday discover that every other RPC protocol needs its own incompatible one-off design.

The same concern applies to serialization. Tbh the .protobuf contract model is also not-so-that-good fit for pentesting. I mean, ofc it's useful when the schema is available, correct, and stable - but in real testing we (often) do not have that luxury and freestyling (I would say). Sometimes reflection is off, contract is missing, or sometimes the interesting part is sending malformed/partial/unexpected. So IMO, strong typing design everywhere may be clean from an engineering perspective, but less useful for offensive testing. (a.k.a. loser structured input/schema might be more useful in practice in this context because it would not always require a strict contract before a template can express a probe/mutation/matcher.)