lesson_learned — Claude Code rule: what it does, how to install
The lesson_learned rule explains why string constants must match fixed-width protocol fields. Use it when changing Go code that reads message headers into fixed-size buffers.
MIT ★ 336 updated 2026-04-09
.claude/rules/LESSON_LEARNED.mdWhat lesson_learned does
The rule describes a Stowaway failure: changing identifier lengths left connections established but broke message exchange. The header fields were read into buffers of fixed size, so differently sized strings disrupted protocol parsing.
Before editing constants, it recommends locating fixed buffer and slice sizes, checking where each value is used, then testing data exchange on both client and server. It distinguishes ordinary strings from values embedded in a protocol. Those values have length constraints; magic bytes must also retain their exact value. A mismatch can drop a connection after authentication succeeds.
To install it in Claude Code, place the rule file at .claude/rules/LESSON_LEARNED.md. The example focuses on Go protocol constants; it does not replace tests of the implementation you are changing.
What it helps with
- check whether a changed constant fits its protocol field
- locate fixed buffer and slice sizes in Go code
- trace an identifier from its definition to header parsing
- test message exchange after changing protocol values
Example prompts for the agent
- Check whether the new string constants match the protocol's fixed-width fields.
- Find Go code where buffer sizes constrain identifier reads.
- Draft client and server checks for message exchange after these protocol constants change.
How to install lesson_learned
Manually: put the files in place
.claude/rules/LESSON_LEARNED.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/LESSON_LEARNED.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/LESSON_LEARNED.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/LESSON_LEARNED.mdManually: put the files in place
.clinerules/LESSON_LEARNED.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about lesson_learned
How do I install lesson_learned in Claude Code?
Place the rule file at .claude/rules/LESSON_LEARNED.md.
What does lesson_learned do?
It explains how changing a protocol constant's length can disrupt header parsing and drop a connection. The rule recommends checking fixed sizes and testing message exchange.
Why does a string constant's length matter in a network protocol?
When code reads a field into a fixed-size buffer, a differently sized string can disrupt parsing. The rule says magic bytes must keep both their length and value.
Source text
LESSON_LEARNED.md · MIT
# Evasion Lesson Learned: Fixed-Length Protocol Fields ## Incident Date 2026-04-09 ## Tool Stowaway (Go-based multi-hop proxy) ## Problem Description During source code modification to evade detection, we changed protocol identifier constants: **Original values:** ```go const ADMIN_UUID = "IAMADMINXD" // 10 characters const TEMP_UUID = "IAMNEWHERE" // 10 characters const TEMP_ROUTE = "THEREISNOROUTE" // 14 characters ``` **Modified values (WRONG):** ```go const ADMIN_UUID = "NODE-CTRL-01" // 12 characters ❌ const TEMP_UUID = "NODE-JOIN-00" // 12 characters ❌ const TEMP_ROUTE = "EMPTY-ROUTE-00" // 15 characters ❌ ``` ## Root Cause The protocol uses **fixed-length fields** in message headers. The code reads exactly 10 bytes for UUID fields: ```go // protocol/raw.go senderBuf := make([]byte, 10) // Fixed 10 bytes for UUID accepterBuf := make([]byte, 10) // Fixed 10 bytes for UUID ``` Changing the UUID length from 10 to 12 characters caused: 1. Message header parsing to read wrong bytes 2. Protocol deserialization failure 3. Connection established but immediately dropped with "connection reset by peer" ## Symptom - Connection was established successfully - Authentication passed - But control panel showed no response - Error message: `read tcp: connection reset by peer` ## Correct Fix ```go const ADMIN_UUID = "CTRL-00001" // 10 characters ✅ const TEMP_UUID = "JOIN-00001" // 10 characters ✅ const TEMP_ROUTE = "NOROUTE00000" // 14 characters ✅ ``` ## Key Lessons ### 1. Always Check Fixed-Length Protocol Fields Before modifying any string constants in networked applications: 1. Search for `make([]byte, N)` where N is a fixed number 2. Search for hardcoded slice lengths like `[:10]`, `[:14]` 3. Check if string constants are used in binary protocols ```bash # Find potential fixed-length reads grep -rn "make(\[\]byte" --include="*.go" grep -rn "\[:10\]" --include="*.go" ``` ### 2. Common Fixed-Length Patterns | Pattern | Description | |---------|-------------| | UUID fields | Often fixed 10-36 bytes | | Message types | Often fixed 1-4 bytes | | Length prefixes | Often 2-4 bytes | | Magic bytes | Often 4-8 bytes | | Route/Path fields | May have fixed max length | ### 3. Verification Checklist After modifying protocol-related constants: - [ ] Count character length of new value - [ ] Compare with original value length - [ ] Search for hardcoded byte lengths in code - [ ] Test connection establishment - [ ] Test message exchange - [ ] Check both client and server side ### 4. Code Review Pattern ```go // DANGEROUS - Length changed const ADMIN_UUID = "NODE-CTRL-01" // Was 10, now 12 // Safe modification approach: // 1. Find all usages grep -rn "ADMIN_UUID" --include="*.go" // 2. Check for fixed-length reads grep -rn "make(\[\]byte.*10)" --include="*.go" // Matches old length // 3. Verify protocol structure // Look for: senderBuf, accepterBuf, UUIDLen fields ``` ## Prevention Rules ### Rule 1: Length Preservation When modifying string constants in network protocols: - **ALWAYS** maintain the exact same character length - **NEVER** assume variable-length handling ### Rule 2: Binary Protocol Analysis For Go/C/C++ network tools: 1. Look for `binary.Read()` / `binary.Write()` 2. Look for `io.ReadFull()` with fixed buffer sizes 3. Look for struct tags like `` `len:"10"` `` ### Rule 3: Test Connection First After modification: 1. Test basic connection establishment 2. Test authentication handshake 3. Test data exchange 4. Only then proceed with full testing ### Rule 4: Protocol Constants Are Special String constants used in protocols are **NOT** like regular strings: - Log messages → Can change freely - Protocol identifiers → MUST maintain length - Magic bytes → MUST maintain exact value AND length ## Files to Update Update the following skill documents: - `tools_evasion/source_modify.md` - Add fixed-length field warning - `tools_evasion/rule_analysis.md` - Add protocol field analysis section ## Related Detection Rules This issue does NOT affect YARA detection since the strings are embedded in binary anyway. The length change was purely a functional bug, not a detection issue. ## Conclusion **When modifying network tools, always check for fixed-length protocol fields before changing string constants.**
© JDArmy · MIT · JDArmy/Evasion-SubAgents