fix(sanitize): preserve angle brackets inside code blocks and inline code

[blackwell-systems]

Description

bluemonday.StrictPolicy() treats angle brackets inside markdown code blocks and inline code spans as HTML tags and strips them. This causes content like mut_raw_ptr<int> in issue/PR bodies to become mut_raw_ptr when read through MCP endpoints.

Before

let ptr: mut_raw_ptr<int> = raw_new int;

Agent sees: let ptr: mut_raw_ptr = raw_new int;

After

Agent sees: let ptr: mut_raw_ptr<int> = raw_new int;

Root cause

FilterHTMLTags calls bluemonday.Sanitize() on the entire markdown body without distinguishing code from prose. Bluemonday treats <int>, <T>, <String>, etc. as unrecognized HTML tags and removes them.

Fix

Before HTML sanitization, replace < and > inside fenced code blocks (```) and inline code spans (`) with null-byte sentinels that bluemonday will not interpret as HTML. After sanitization, restore the sentinels to angle brackets.

This preserves XSS protection for angle brackets in prose (e.g. <script> is still stripped) while keeping angle brackets inside code intact.

Testing

Added 6 test cases covering:

• Fenced code blocks with angle brackets (the reported bug)
• Inline code with generic types (Vec<String>)
• Angle brackets outside code still sanitized (XSS protection preserved)
• Multiple inline code spans
• Fenced code with language info string

Fixes #2202

[SamMorrowDrums]

Thanks for this @blackwell-systems — the approach is sound and the security trade-off is defensible. bluemonday continues to handle prose, and the sentinel design has the right ordering: FilterInvisibleCharacters strips NUL bytes before protectCodeAngleBrackets runs, so an attacker can't forge sentinels in the input.

Cc'ing @joannakl as a fellow maintainer — would appreciate a second pair of eyes since this touches the sanitizer.

I've left two inline suggestions to harden the contract (ordering invariant + sentinel doc). One bigger consideration:

Have you considered a CommonMark parser? github.com/yuin/goldmark is already a transitive dep in go.sum. I prototyped a drop-in replacement for protectCodeAngleBrackets against this branch:

func protectCodeAngleBrackets(input string) string {
    src := []byte(input)
    doc := goldmark.DefaultParser().Parse(text.NewReader(src))

    type span struct{ start, stop int }
    var spans []span
    _ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
        if !entering {
            return ast.WalkContinue, nil
        }
        switch n.Kind() {
        case ast.KindFencedCodeBlock, ast.KindCodeBlock:
            lines := n.Lines()
            for i := 0; i < lines.Len(); i++ {
                seg := lines.At(i)
                spans = append(spans, span{seg.Start, seg.Stop})
            }
        case ast.KindCodeSpan:
            for c := n.FirstChild(); c != nil; c = c.NextSibling() {
                if t, ok := c.(*ast.Text); ok {
                    seg := t.Segment
                    spans = append(spans, span{seg.Start, seg.Stop})
                }
            }
        }
        return ast.WalkContinue, nil
    })

    if len(spans) == 0 {
        return input
    }
    var out bytes.Buffer
    out.Grow(len(src))
    cursor := 0
    for _, s := range spans {
        out.Write(src[cursor:s.start])
        for _, b := range src[s.start:s.stop] {
            switch b {
            case '<':
                out.WriteString(ltSentinel)
            case '>':
                out.WriteString(gtSentinel)
            default:
                out.WriteByte(b)
            }
        }
        cursor = s.stop
    }
    out.Write(src[cursor:])
    return out.String()
}

About 40 lines instead of 150, and it picks up indented (4-space) code blocks for free, which the current scanner misses:

Text

    let x: Vec<u8> = vec![];

I ran it against the same edge cases (4-backtick fences, nested backticks, unclosed fences, sentinel-injection probes, <script> inside fences, etc.) and behavior matches or improves on the hand-rolled version. NUL-strip ordering is preserved, so the sentinel-collision defense is unchanged.

Would also let us drop ~150 lines and rely on a CommonMark-compliant parser for future edge cases (autolinks adjacent to fences, etc.).

Happy with this either way — if you'd rather land the current approach and follow up, that's totally fine. Up to you and @joannakl. 🙏

A non-blocking nit: the package doc would be a good place to write down the threat model (input source: untrusted GitHub content; goal: strip HTML from prose without corrupting code) so the next reader has the context up front.

[SamMorrowDrums]

Optional: pull out the ordering as a named invariant so future readers don't accidentally reorder these calls. The security argument relies on FilterInvisibleCharacters running first (so NUL is stripped before sentinels are introduced) and on restoreCodeAngleBrackets running last (after FilterHTMLTags).

Suggested change

	func Sanitize(input string) string {
	return FilterHTMLTags(FilterCodeFenceMetadata(FilterInvisibleCharacters(input)))
	cleaned := FilterCodeFenceMetadata(FilterInvisibleCharacters(input))
	// Protect angle brackets inside code blocks and inline code spans
	// from being stripped by the HTML sanitizer. bluemonday treats <int>,
	// <T>, etc. as unknown HTML tags and removes them.
	// See https://github.com/github/github-mcp-server/issues/2202
	protected := protectCodeAngleBrackets(cleaned)
	sanitized := FilterHTMLTags(protected)
	return restoreCodeAngleBrackets(sanitized)
	func Sanitize(input string) string {
	// Ordering is security-load-bearing:
	// 1. FilterInvisibleCharacters strips NUL bytes BEFORE sentinels are
	// introduced, preventing an attacker from forging \x00LT\x00 in input.
	// 2. protectCodeAngleBrackets replaces < and > inside code with sentinels
	// so bluemonday does not strip them as HTML.
	// 3. FilterHTMLTags (bluemonday) sanitizes prose; sentinels pass through.
	// 4. restoreCodeAngleBrackets converts sentinels back to < and >.
	// See https://github.com/github/github-mcp-server/issues/2202
	cleaned := FilterCodeFenceMetadata(FilterInvisibleCharacters(input))
	protected := protectCodeAngleBrackets(cleaned)
	sanitized := FilterHTMLTags(protected)
	return restoreCodeAngleBrackets(sanitized)
	}

[SamMorrowDrums]

Worth noting in the doc comment that the NUL-stripping in FilterInvisibleCharacters is what makes these sentinels collision-free — it's a non-obvious dependency.

Suggested change

	// Sentinels used to protect angle brackets inside code from HTML sanitization.
	// These are chosen to be unlikely to appear in real content.
	const (
	ltSentinel = "\x00LT\x00"
	gtSentinel = "\x00GT\x00"
	)
	// Sentinels used to protect angle brackets inside code from HTML sanitization.
	// They embed NUL bytes, which are stripped from all input by
	// FilterInvisibleCharacters before this function runs — that strip is what
	// makes the sentinels collision-free against attacker-controlled input.
	const (
	ltSentinel = "\x00LT\x00"
	gtSentinel = "\x00GT\x00"
	)

[blackwell-systems]

@SamMorrowDrums Thanks for the goldmark suggestion and prototype! You're right that it's cleaner and more maintainable.

I've refactored to use goldmark's CommonMark parser. Changes:

1. Replaced hand-rolled scanner with goldmark AST walker (~150 lines → ~40 lines)
2. Added indented code block coverage (4-space blocks now protected)
3. Added package documentation with threat model
4. Documented ordering invariant (FilterInvisibleCharacters before protectCodeAngleBrackets)
5. Updated sentinel documentation explaining collision prevention

All existing tests pass plus a new test for indented code blocks. Ran script/lint locally (0 issues) and go test -race ./....

Happy to address the inline suggestions if there's anything else needed. Thanks again for the detailed review.