memory-safe-migration - SKILL.md Agent Skill

name: memory-safe-migration description: >- Guide secure migration of code from memory-unsafe languages (C, C++, Assembly) to memory-safe languages (Rust, Go, Java, C#, Swift). Use when migrating or rewriting legacy C/C++ code, designing FFI boundaries between safe and unsafe code, writing new modules in existing C/C++ codebases, reviewing mixed-language projects, planning memory safety roadmaps, or when an AI agent is about to generate new C/C++ code that could be written in a memory-safe language instead. Also triggers on CISA/NSA memory safety compliance discussions. license: CC-BY-4.0 metadata: author: codeguard-community version: "1.0" category: memory-safety

Memory-safe language migration

When this skill activates

User asks to migrate, port, or rewrite C/C++ code to Rust, Go, Java, C#, or Swift
User asks to add a new module or feature to an existing C/C++ project
User asks to design an FFI boundary between safe and unsafe code
User asks about memory safety roadmaps or CISA/NSA compliance
User asks to review mixed-language code for safety issues
AI agent is about to generate new C/C++ code — check if an MSL alternative is viable

Decision: new code language selection

Before writing any new code, ask:

Is there an explicit constraint requiring C/C++? (bare-metal with no MSL runtime, hard real-time below 1μs, existing codebase policy)
If no constraint exists, default to a memory-safe language
Select the target language using the guide in references/language-selection.md

If the project is predominantly C/C++, write the new module in an MSL and integrate via FFI. See references/ffi-security.md for boundary rules.

Migration workflow

Follow these steps for every migration task:

Step 1: Assess the component

Run the assessment script to evaluate migration priority and feasibility:

python scripts/assess-migration.py --file <source_file>

Or manually evaluate using the checklist in references/assessment-checklist.md.

Priority order for migration:

Network-facing code (parsers, protocol handlers, TLS)
Code handling untrusted input (file parsers, deserialization)
Cryptographic implementations
Privilege boundary code (auth enforcement)
Code with a history of memory-related CVEs
Internal utility code

Step 2: Write tests first

Never migrate a component without test coverage. If no tests exist, write them against the C/C++ implementation before touching anything. These tests become the correctness oracle for the new implementation.

Step 3: Migrate incrementally

One function or module at a time. Never rewrite an entire codebase in one pass. Follow the Android model: new code in MSL, existing stable code stays in place, proportion of unsafe code decreases over time.

For common migration patterns (buffers, strings, concurrency, error handling), see references/migration-patterns.md.

Step 4: Secure the FFI boundary

Every interface between safe and unsafe code is a security boundary. Follow all rules in references/ffi-security.md. Key rules:

Validate all inputs from the unsafe side (null checks, bounds checks, type checks)
Minimize unsafe blocks — wrap only the minimum necessary operation
Document every unsafe block with a // SAFETY: comment
The allocator that created memory must free it — never mix allocators
Never panic across FFI boundaries
Catch all panics with std::panic::catch_unwind at FFI entry points

Step 5: Validate

After every migration unit, verify:

All existing tests pass against the new implementation
No new unsafe surface without documented safety invariants
FFI boundaries fuzzed with malformed inputs, null pointers, extreme lengths
Memory safety tools run clean (Miri for Rust, race detector for Go, ASan for C side)
Performance benchmarked against the original — no unacceptable regression
All new MSL dependencies audited for trustworthiness and active maintenance

Step 6: Update build and CI

Integrate the MSL toolchain (cargo, go build, etc.) into the existing build system
Add MSL-specific linting (clippy for Rust, go vet for Go)
Add formatting checks (rustfmt, gofmt)
Add safety-specific CI checks (deny unsafe without annotation, dependency audit)

Anti-patterns to prevent

Never do these during migration:

Wrapping unsafe C in a "safe" API without actual safety guarantees — if the wrapper just passes through without validation, it provides false confidence
Using unsafe to replicate C-style patterns in Rust — if extensive unsafe is needed, the approach should be redesigned or the code should remain in C
Migrating without tests — write tests for C/C++ first, then validate MSL version
Ignoring error handling differences — C uses return codes, Rust uses Result, Go uses multiple returns. Every error path must be explicitly mapped
Assuming GC languages need no resource discipline — they prevent memory corruption but can still leak file handles, sockets, and connections. Use defer, try-with-resources, using, or with patterns
Migrating performance-critical loops without benchmarking — verify first

References

For detailed guidance on specific topics: