windows_exporter/internal/headers/clusapi/properties.go

// SPDX-License-Identifier: Apache-2.0
//
// Copyright The Prometheus Authors
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package clusapi

import (
	"encoding/binary"
	"errors"
	"fmt"
	"strings"
	"unicode"
	"unicode/utf16"
)

const (
	propertyName         = 0x00040003
	propertyValue        = 0x00010000
	formatDWORD          = 2
	formatString         = 3
	formatExpandString   = 4
	formatLong           = 7
	formatExpandedString = 8
)

// Property is a single CLUSPROP_LIST_VALUE. Values retain their native format;
// unsupported formats can be skipped without confusing an absent DWORD with zero.
type Property struct {
	Format uint16
	Data   []byte
}

func (p Property) DWORD() (uint32, error) {
	value, ok := p.dword()
	if !ok {
		return 0, fmt.Errorf("expected DWORD, format %d, length %d", p.Format, len(p.Data))
	}

	return value, nil
}

// dword is DWORD without the error, for callers that skip other formats.
func (p Property) dword() (uint32, bool) {
	if p.Format != formatDWORD || len(p.Data) != 4 {
		return 0, false
	}

	return binary.LittleEndian.Uint32(p.Data), true
}

// String decodes an SZ, EXPAND_SZ or EXPANDED_SZ value like WMI does: the value
// ends at the first NUL and invalid UTF-16 is replaced with U+FFFD.
func (p Property) String() (string, error) {
	switch p.Format {
	case formatString, formatExpandString, formatExpandedString:
		return decodeString(p.Data), nil
	default:
		return "", fmt.Errorf("expected string, format %d", p.Format)
	}
}

// Value32 returns the bit pattern of a DWORD or LONG value. Callers decide the
// signedness, matching the WMI type of the property they publish.
func (p Property) Value32() (uint32, error) {
	value, ok := p.value32()
	if !ok {
		return 0, fmt.Errorf("expected DWORD or LONG, format %d, length %d", p.Format, len(p.Data))
	}

	return value, nil
}

// value32 is Value32 without the error, for callers that skip other formats.
func (p Property) value32() (uint32, bool) {
	if (p.Format != formatDWORD && p.Format != formatLong) || len(p.Data) != 4 {
		return 0, false
	}

	return binary.LittleEndian.Uint32(p.Data), true
}

// ParseProperties decodes CLUSPROP_LIST without casting untrusted bytes to native
// structs. Headers and payloads are DWORD aligned; cbLength is measured in bytes.
// Only the structure is validated: string contents are decoded when used, so one
// unusual value does not discard the whole list.
// https://learn.microsoft.com/en-us/previous-versions/windows/desktop/mscs/property-lists
func ParseProperties(data []byte) (map[string][]Property, error) {
	if len(data) < 4 {
		return nil, errors.New("property list is missing its count")
	}

	count := binary.LittleEndian.Uint32(data)

	data = data[4:]
	if uint64(count) > uint64(len(data))/16 {
		return nil, errors.New("property count exceeds buffer")
	}

	properties := make(map[string][]Property, count)
	// Nearly every property has a single value, so all value lists share
	// one backing array instead of one allocation per property.
	all := make([]Property, 0, count)

	for range count {
		if len(data) < 8 || binary.LittleEndian.Uint32(data) != propertyName {
			return nil, errors.New("invalid property name header")
		}

		nameBytes, rest, err := propertyPayload(data)
		if err != nil {
			return nil, err
		}

		name := decodeString(nameBytes)
		data = rest
		start := len(all)

		for {
			if len(data) < 4 {
				return nil, fmt.Errorf("missing endmark for %q", name)
			}

			syntax := binary.LittleEndian.Uint32(data)
			if syntax == 0 {
				data = data[4:]

				break
			}

			if syntax&0xffff0000 != propertyValue {
				return nil, fmt.Errorf("invalid value syntax %#x for %q", syntax, name)
			}

			payload, rest, err := propertyPayload(data)
			if err != nil {
				return nil, fmt.Errorf("property %q: %w", name, err)
			}

			format := uint16(syntax)
			if (format == formatDWORD || format == formatLong) && len(payload) != 4 {
				return nil, fmt.Errorf("invalid DWORD length for %q", name)
			}

			all = append(all, Property{Format: format, Data: payload})
			data = rest
		}

		// Keep the first occurrence; a repeated name does not affect the structure.
		// The full slice expression keeps appends for later properties from
		// writing into this list.
		if _, exists := properties[name]; !exists {
			properties[name] = all[start:len(all):len(all)]
		}
	}

	// Lists returned by the cluster service end with a CLUSPROP_SYNTAX_ENDMARK
	// after the last value list. Accept zero padding, reject anything else.
	for _, b := range data {
		if b != 0 {
			return nil, fmt.Errorf("%d bytes of trailing property list data starting with % x", len(data), data[:min(len(data), 16)])
		}
	}

	return properties, nil
}

func propertyPayload(data []byte) ([]byte, []byte, error) {
	if len(data) < 8 {
		return nil, nil, errors.New("truncated property header")
	}

	length := uint64(binary.LittleEndian.Uint32(data[4:]))

	aligned := (length + 3) &^ uint64(3)
	if aligned > uint64(len(data)-8) {
		return nil, nil, errors.New("property payload exceeds buffer")
	}

	return data[8 : 8+length], data[8+aligned:], nil
}

// decodeString decodes little-endian UTF-16 bytes. A trailing odd byte is ignored.
func decodeString(data []byte) string {
	// Names and type strings are short; converting them on the stack leaves
	// the result as the only allocation.
	var stack [128]uint16

	units := stack[:0]
	if len(data)/2 > len(stack) {
		units = make([]uint16, 0, len(data)/2)
	}

	// Stop at the first NUL: fixed-size fields such as MAX_PATH names would
	// otherwise always outgrow the stack buffer.
	for i := 0; i+1 < len(data); i += 2 {
		unit := binary.LittleEndian.Uint16(data[i:])
		if unit == 0 {
			break
		}

		units = append(units, unit)
	}

	return decodeUnits(units)
}

// decodeUnits ends the string at the first NUL and replaces invalid UTF-16 with
// U+FFFD, matching the strings WMI returned for the same names. It decodes like
// utf16.Decode, but writes straight into the result instead of a []rune.
func decodeUnits(units []uint16) string {
	for i, unit := range units {
		if unit == 0 {
			units = units[:i]

			break
		}
	}

	var builder strings.Builder

	builder.Grow(len(units))

	for i := 0; i < len(units); i++ {
		r := rune(units[i])

		if utf16.IsSurrogate(r) {
			decoded := unicode.ReplacementChar
			if i+1 < len(units) {
				decoded = utf16.DecodeRune(r, rune(units[i+1]))
			}

			if decoded != unicode.ReplacementChar {
				i++
			}

			r = decoded
		}

		builder.WriteRune(r)
	}

	return builder.String()
}