Proposing a New Signal Type¶

// Signal defines the interface for a recognized signal type.
type Signal interface {
    // Name returns the signal type identifier (e.g., "cvss", "epss").
    // Must be lowercase, underscore-separated, unique across all registered signals.
    Name() string // (1)!

    // Description returns a single-sentence human-readable description.
    Description() string // (2)!

    // Fields returns the list of accepted input field names.
    // Used for documentation and the `ores signals` / ListSignals output.
    Fields() []string // (3)!

    // Validate checks that raw is a valid input for this signal.
    // Returns a descriptive error if invalid, nil if valid.
    // Must not modify raw.
    Validate(raw any) error // (4)!

    // Normalize converts raw to a NormalizedSignal (map[string]float64).
    // All factor values must be in [0.0, 1.0].
    // Must call Validate internally and return its error if validation fails.
    Normalize(raw any) (NormalizedSignal, error) // (5)!
}

package parsers

import (
    "errors"
    "fmt"

    "github.com/rigsecurity/ores/pkg/signals"
)

// MySignal parses <description of what this signal represents>.
type MySignal struct{}

func (m *MySignal) Name() string { return "my_signal" }

func (m *MySignal) Description() string {
    return "Short description of what this signal provides"
}

func (m *MySignal) Fields() []string {
    return []string{"field_one", "field_two"}
}

func (m *MySignal) Validate(raw any) error {
    mRaw, ok := raw.(map[string]any)
    if !ok {
        return errors.New("my_signal: input must be a map")
    }

    hasAny := false

    if val, ok := mRaw["field_one"]; ok {
        hasAny = true
        f, ok := toFloat64(val)
        if !ok {
            return fmt.Errorf("my_signal: field_one must be a number, got %T", val)
        }
        if f < 0 || f > 1 {
            return fmt.Errorf("my_signal: field_one must be in [0, 1], got %v", f)
        }
    }

    if val, ok := mRaw["field_two"]; ok {
        hasAny = true
        if _, ok := toBool(val); !ok {
            return fmt.Errorf("my_signal: field_two must be a bool, got %T", val)
        }
    }

    if !hasAny {
        return errors.New("my_signal: at least one of field_one or field_two is required")
    }

    return nil
}

func (m *MySignal) Normalize(raw any) (signals.NormalizedSignal, error) {
    if err := m.Validate(raw); err != nil {
        return nil, err
    }

    mRaw := raw.(map[string]any)
    ns := make(signals.NormalizedSignal)

    if val, ok := mRaw["field_one"]; ok {
        f, _ := toFloat64(val)
        ns["my_factor_name"] = f // already in [0, 1]
    }

    if val, ok := mRaw["field_two"]; ok {
        b, _ := toBool(val)
        if b {
            ns["my_other_factor"] = 1.0
        } else {
            ns["my_other_factor"] = 0.0
        }
    }

    return ns, nil
}

func RegisterAll(r *signals.Registry) {
    r.Register(&CVSS{})
    r.Register(&EPSS{})
    r.Register(&NIST{})
    r.Register(&Asset{})
    r.Register(&ThreatIntel{})
    r.Register(&BlastRadius{})
    r.Register(&Patch{})
    r.Register(&Compliance{})
    r.Register(&MySignal{}) // <-- add this line
}

package parsers_test

import (
    "testing"

    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"

    "github.com/rigsecurity/ores/pkg/signals/parsers"
)

func TestMySignal_Validate(t *testing.T) {
    t.Parallel()

    s := &parsers.MySignal{}

    tests := []struct {
        name    string
        input   any
        wantErr bool
    }{
        {
            name:    "valid field_one",
            input:   map[string]any{"field_one": 0.5},
            wantErr: false,
        },
        {
            name:    "invalid: not a map",
            input:   "string",
            wantErr: true,
        },
        {
            name:    "invalid: field_one out of range",
            input:   map[string]any{"field_one": 1.5},
            wantErr: true,
        },
        {
            name:    "invalid: no fields",
            input:   map[string]any{},
            wantErr: true,
        },
    }

    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            err := s.Validate(tc.input)
            if tc.wantErr {
                assert.Error(t, err)
            } else {
                assert.NoError(t, err)
            }
        })
    }
}

func TestMySignal_Normalize(t *testing.T) {
    t.Parallel()

    s := &parsers.MySignal{}

    t.Run("field_one produces correct factor", func(t *testing.T) {
        t.Parallel()
        ns, err := s.Normalize(map[string]any{"field_one": 0.6})
        require.NoError(t, err)
        assert.InDelta(t, 0.6, ns["my_factor_name"], 0.001)
    })
}