---
name: smb-v10-message-structure
description: Implement and organize SMB 1.0 (CIFS) message code in the Manticore project — command Request/Response structs, the command-casting dispatcher, reserved/obsolete command stubs, AndX extended-response variants, and NT_TRANSACT subcommand payloads with their NtTransactRequest/Response builders and parsers. Use this skill whenever adding or fixing an SMB_COM_* command, wiring a command code into the dispatcher, implementing an MS-SMB extended response, or adding an NT_TRANSACT / TRANSACTION2 subcommand payload and its builders. Triggers include "add an SMB command", "implement SMB_COM_X", "wire a command code", "add an extended response", "implement an NT_TRANSACT subcommand", "wire subcommand structs into NtTransact builders", or "add an SMB transaction payload". For DCE/RPC interfaces (NDR/opnums/idlgen) use the dcerpc-interface-structure skill instead — this skill is the SMB message layer below it.
---

# SMB 1.0 (CIFS) Message Code Structure

How to lay out and implement SMB 1.0 message code in the Manticore repo under `network/smb/smb_v10`. This is the **SMB message layer** — distinct from the DCE/RPC interface layer (see the `dcerpc-interface-structure` skill). DCE/RPC rides on `SMB_COM_TRANSACTION`/named-pipe reads, *not* on the NT_TRANSACT subcommands covered here, so the two skills do not overlap.

Everything here was derived from implementing the full CIFS command set, the MS-SMB server-response extensions, and the NT_TRANSACT subcommand payloads against the official MS-CIFS / MS-SMB / MS-FSCC specifications.

## Core principle

**Verify every wire layout against the official spec before writing code, and never guess a format the spec does not pin down.**

- WebFetch the exact MS-CIFS / MS-SMB / MS-FSCC section for the command/structure and copy field names and byte sizes verbatim. The section is linked from the issue or found via the [MS-CIFS] SMB_COM command-code table.
- Cross-spec: a command in MS-CIFS often references a record defined in MS-FSCC (e.g. `FILE_NOTIFY_INFORMATION` [MS-FSCC] 2.7.1, `FILE_QUOTA_INFORMATION` [MS-FSCC] 2.4.41) or a self-relative `SECURITY_DESCRIPTOR` in MS-DTYP 2.4.6. Fetch the referenced page too.
- If the spec gives no marshallable format (obsolete/reserved commands; opaque blobs like a security descriptor), model it as a documented empty stub or opaque `[]byte` — do **not** reconstruct a legacy `[XOPEN-SMB]`/`[SMB-LM1X]` layout from memory.
- All multi-byte integers are **little-endian**.

## Directory layout

```
network/smb/smb_v10/
  message/
    commands/                      one file per SMB_COM_* command
      <Command>Request.go          e.g. NtTransactRequest.go, NtCreateAndxResponse.go
      <Command>Response.go
      0.command_casting.go         the command-code → struct dispatcher (two switches)
      command_interface/           the CommandInterface + embedded Command base
      andx/                        the AndX block (chained commands)
      codes/codes.go               SMB_COM_* CommandCode constants + name map
    parameters/                    the SMB parameter block (WordCount + Words)
    data/                          the SMB data block (ByteCount + Bytes)
    header/, header/flags{,2}/     SMB header + flag bits
  subcommands/                     TRANSACTION / TRANSACTION2 / NT_TRANSACT subcommand
                                   payload structs + enums (FSCTL codes, FILE_* records)
  types/                           SMB/MS-DTYP type aliases (UCHAR, USHORT, ULONG, …)
```

Key fact: **`types.UCHAR = uint8` is an alias**, so `[]types.UCHAR` *is* `[]byte` — pass command `Parameters`/`Data` slices straight to functions taking `[]byte` with no conversion.

## A command Request/Response struct

Each command embeds `command_interface.Command` and implements `Marshal`/`Unmarshal` plus a `New<Command>Request()` constructor that sets the command code. The base `Command` provides `GetParameters()`/`GetData()` (the `parameters.Parameters` and `data.Data` blocks). Mirror an existing well-formed command (e.g. `OpenResponse.go`) rather than starting blank.

Marshal pattern:
1. Lazily create Parameters/Data if nil.
2. If AndX, fold the AndX words into the parameter block first (`for _, p := range c.GetAndX().GetParameters() { c.GetParameters().AddWord(p) }`).
3. Build `rawParametersContent []byte` field-by-field (little-endian), then `c.GetParameters().AddWordsFromBytesStream(rawParametersContent)`.
4. Build `rawDataContent []byte`, then `c.GetData().Add(rawDataContent)`.
5. Marshal parameters then data.

**The `parameters` block enforces `WordCount == len(Words)`** (`parameters.Marshal` errors otherwise, and `AddWordsFromBytesStream` sets `WordCount = len(bytes)/2`). You therefore cannot emit a `WordCount` that disagrees with the actual word bytes — see the extended-response quirk below.

Unmarshal pattern: unmarshal the Parameters and Data blocks, early-return on the all-empty case (it is an error response carrying only a header `Status`), then decode fields by offset. For AndX responses, skip the 4-octet AndX block (`offset += 4`) before the first real parameter.

Always add the command code to `allCommandCodes` in `nil_unmarshal_sweep_test.go` — a sweep test that calls `Unmarshal` on a fresh struct with 3 zero bytes and must not panic. (This is why `Unmarshal` must lazily init Parameters/Data.)

## The command-casting dispatcher

`0.command_casting.go` has **two switches**, `CreateRequestCommand` and `CreateResponseCommand`, mapping a `codes.CommandCode` to `New<Command>Request()` / `New<Command>Response()`. Both end in a `default` that returns `command code not supported: %d`. A command is only reachable once it has a `case` in **both** switches. The two `default` blocks are textually identical — when scripting an insertion, split the file on the default block and insert before the first (request) and second (response) occurrence.

## Reserved / obsolete command stubs

Many `SMB_COM_*` codes are declared in `codes.go` but were never implemented. Two MS-CIFS statuses:

- **N — reserved, never defined** (e.g. `SMB_COM_NEW_FILE_SIZE`, `SMB_COM_QUERY_SERVER`).
- **X — obsolete, real in a legacy dialect but the format lives only in `[SMB-LM1X]`/`[XOPEN-SMB]`/`[SMB-CORE]`, which MS-CIFS does not reproduce** (e.g. `SMB_COM_COPY`, `SMB_COM_MOVE`, `SMB_COM_READ_MPX_SECONDARY`).

For **both** N and X codes, the spec only says "servers SHOULD/MUST return `STATUS_NOT_IMPLEMENTED`" and gives no marshallable format, and the completeness issues ask only to "route the code to a defined handler instead of failing." So both get the **same empty-framing stub**, differing only in doc wording:

- `<Name>Request`/`<Name>Response` embedding `command_interface.Command`, constructor `New<Name>Request()` setting the code.
- `Marshal`/`Unmarshal` emit/consume only the empty `WordCount`(1) + `ByteCount`(2) framing — i.e. marshalled output is exactly `00 / 00 00`.
- Doc comment cites the MS-CIFS section and the SHOULD/MUST `STATUS_NOT_IMPLEMENTED` rule; for X codes note the legacy reference (`[SMB-LM1X]`/`[XOPEN-SMB]`/`[SMB-CORE]`) that MS-CIFS does not republish.
- Wire into both dispatcher switches; add to the `allCommandCodes` sweep.
- Test: dispatch resolves (not the `default` error) + the empty `00 / 00 00` framing round-trips.

`SMB_COM_NO_ANDX_COMMAND` (0xFF) terminates an AndX chain; `SMB_COM_INVALID` (0xFE) is not a real code.

## AndX extended-response variants (MS-SMB)

Some AndX responses have a base CIFS form and a larger MS-SMB form selected by a request flag (`NT_CREATE_ANDX` extended response [MS-SMB] 2.2.4.9.2; `TREE_CONNECT_ANDX` extended response [MS-SMB] 2.2.4.7.2). Model the extension on the existing response struct:

- Add an `Extended bool` selector field plus the extra fields (e.g. `VolumeGUID [16]byte`, `FileId uint64`, `MaximalAccessRights types.ULONG`).
- `Marshal` appends the extra fields after the base fields **only when `Extended`** — the base layout stays byte-identical otherwise.
- `Unmarshal` detects the extended form by the **presence of the extra parameter octets** after the base fields (e.g. "if ≥32 more parameter octets follow `Directory`, set `Extended` and read them"), then decodes them.

**WordCount quirk (NT_CREATE_ANDX extended):** [MS-SMB] says the extended `WordCount` SHOULD be `0x2A` (42), but the extended Words block is actually 50 words (the 4 extra fields add 32 octets to the 68-octet base). Because the `parameters` layer enforces `WordCount == len(Words)`, the implementation emits the **self-consistent** `0x32` (50) and documents the spec's fixed `0x2A` in a comment. Do not try to force `0x2A` — it would desync framing. `TREE_CONNECT_ANDX` has no such quirk (3 → 7 words, consistent).

## NT_TRANSACT subcommands

`SMB_COM_NT_TRANSACT` (0xA0) is a generic container ([MS-CIFS] 2.2.4.62.1). Its Words end with `…SetupCount(1), Function(2), Setup[SetupCount]` — **`Function` (the subcommand code) is separate from the `Setup` words**, and `Setup` is `SetupCount` two-byte words *after* `Function`. The `SMB_Data` is `Pad1, NT_Trans_Parameters[ParameterCount], Pad2, NT_Trans_Data[DataCount]`.

Where each subcommand puts its arguments varies — always check the per-subcommand section:

| Subcommand | Function | Args carried in | Notes |
|---|---|---|---|
| NOTIFY_CHANGE | 0x0004 | **Setup** (CompletionFilter4+FID2+WatchTree1+Reserved1) | response: `FILE_NOTIFY_INFORMATION` list in NT_Trans_Parameters |
| QUERY/SET_SECURITY_DESC | 0x0006 / 0x0003 | NT_Trans_Parameters (FID2+Reserved2+SecurityInformation4) | descriptor = opaque NT_Trans_Data; query response param = LengthNeeded4 |
| QUERY_QUOTA | 0x0007 | NT_Trans_Parameters (16 octets) | SidList = NT_Trans_Data; response = DataLength4 + `FILE_QUOTA_INFORMATION` list |
| IOCTL (copychunk, snapshots, resume-key) | 0x0002 | **Setup** = FunctionCode4+FID2+IsFsctl1+IsFlags1 | FSCTL payload = NT_Trans_Data |

Subcommand **payload structs** live in `subcommands/` (e.g. `srv_copychunk.go`, `srv_snapshot_array.go`, `nt_transact_quota.go`, `nt_transact_notify_change.go`, `nt_transact_security_desc.go`), each with `Marshal`/`Unmarshal` and `SetupCount`/`ChunkCount`/length fields **derived from slice lengths**, not stored redundantly. The FSCTL function codes (`FSCTL_SRV_REQUEST_RESUME_KEY` 0x00140078, `FSCTL_SRV_COPYCHUNK` 0x001440F2, `FSCTL_SRV_ENUMERATE_SNAPSHOTS` 0x00144064) live with their structs.

### Wiring subcommand structs into NtTransactRequest/Response

`NtTransactRequest` carries `Setup []types.USHORT` (added so notify-change and IOCTL subcommands are representable; `SetupCount` is derived from `len(Setup)` on marshal). Builders + parsers live in `message/commands/NtTransactSubcommandBuilders.go` (the `commands` package may import `subcommands` — `subcommands` imports nothing from `commands`, so there is no cycle).

- **Request builders** return a populated `*NtTransactRequest`: set `Function`, the `Setup` words (notify-change setup, or `NewNtTransactIoctlSetup(fsctl, fid, true, 0)` for the FSCTLs), `NT_Trans_Parameters`/`NT_Trans_Data` from the subcommand struct's `Marshal()`, and the counts (`TotalParameterCount`/`ParameterCount`, `TotalDataCount`/`DataCount`, `MaxParameterCount`/`MaxDataCount`).
- **Response parsers** are methods on `*NtTransactResponse` that read `c.Parameters`/`c.Data` (both `[]types.UCHAR` = `[]byte`) into the typed structs.
- To pack a subcommand's little-endian setup byte block into `Setup []USHORT`, read it back as LE `uint16` words.

**Offset-sensitivity gotcha:** a full `NtTransactRequest` `Marshal`→`Unmarshal` round-trip reconstructs `Pad1`/`Pad2` from the **header-relative** `ParameterOffset`/`DataOffset`. Builders deliberately do **not** set those offsets — they are computed at message-assembly time once the header position is known. Consequence for tests: round-trip the **setup-only** case (notify-change) end-to-end, and validate the param/data builders by **re-parsing the populated `NT_Trans_Parameters`/`NT_Trans_Data` fields** rather than a full request round-trip. Large transfers spanning `NT_TRANSACT_SECONDARY` are also a higher-level concern, not the builder's.

## Tests

- **Golden bytes** for fixed layouts: marshal a struct with known field values and assert the exact octet sequence (use real example bytes from the spec trace where available, e.g. the 24-byte copychunk resume key).
- **Round-trip** for variable/derived layouts: marshal → unmarshal → compare.
- **Dispatch** for new command codes: `CreateRequestCommand`/`CreateResponseCommand` resolve without the generic error.
- Add the code to the `nil_unmarshal_sweep_test.go` `allCommandCodes` list.
- None of these obscure paths are live-validated against a server — say so in the PR; golden + round-trip tests are the acceptance gate.

## Checklist when adding an SMB command or subcommand

1. WebFetch the MS-CIFS/MS-SMB/MS-FSCC section; copy field names + byte sizes verbatim. Note the SHOULD/MUST status and whether a format is even defined.
2. Decide the shape: full command struct, reserved/obsolete empty stub, AndX extended variant, or NT_TRANSACT subcommand payload + builder/parser.
3. Implement `Marshal`/`Unmarshal` (little-endian; derive counts from lengths; lazily init Parameters/Data).
4. For commands: wire **both** dispatcher switches + add to the `allCommandCodes` sweep. For subcommands: add builder(s) + response parser(s); ensure `Setup` is set for setup-carrying subcommands.
5. Tests: golden + round-trip (+ dispatch for commands). `gofmt`, `go build ./...`, `go vet`, `go test ./network/smb/smb_v10/...`.
6. Per the Bug-Fixes-Commit-and-PR / Issue-Commit-and-PR skills: branch from `main`, focused commit with a `Fixes #<n>` closing keyword, PR via the template, no Claude attribution. Note in the PR that the path is not live-validated.