Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/LESSON_LEARNED.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

IDE rules catalog →

From the same set22

The whole set →
rule_mapping rule_mapping is a Claude Code rule that analyzes YARA and Sigma signatures for AdaptixC2. It helps assess which signatures are outdated during detection rule reviews. CX Codex +1 ★ 336repo stars tools_evasion The tools_evasion command examines a penetration-testing tool, gathers detection rules, then changes its source code to avoid those rules. It is intended for authorized security work. CX Codex +1 ★ 336repo stars rule_inventory A rule file that gives the agent an inventory of SharpHound detections: three YARA rules, one Sigma rule, pattern tables and a difficulty rating for each. CX Codex +1 ★ 336repo stars hex_analysis hex_analysis — a rule file that explains YARA hex signatures for AdaptixC2: which instruction produced each one and which compiler flag moves those bytes. CX Codex +1 ★ 336repo stars behavior_analysis behavior_analysis — a rule file that tables how SharpHound gives itself away and what the doc suggests changing in the build, the flags and the output files. CX Codex +1 ★ 336repo stars modifications_summary modifications_summary keeps a record of the AdaptixC2 YARA-evasion edits in front of Claude: beacon build flags, renamed Go functions and the commands that verify them. Useful when you pick the repo back up. CX Codex +1 ★ 336repo stars behavior_analysis behavior_analysis — a Claude Code rule that loads a structured behavioral profile of Stowaway into the agent context: CLI flags, protocol constants, build artifacts, and tiered detection indicators. CX Codex +1 ★ 336repo stars modifications_summary modifications_summary — a Claude rule that fixes the shape of a change log for tool modifications: build metadata, log strings, filenames, and which detections still fire. CX Codex +1 ★ 336repo stars

Project sponsors

Companies that keep this analytics open