ARTEX/notify/feishu.go

package notify

import (
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"strconv"
	"time"
)

// feishuChannel implements the Feishu (incl. Lark) custom bot, using interactive
// cards.
//
// Platform traits:
//   - The signing algorithm is **different** from DingTalk's and extremely easy to
//     get wrong; see the feishuSign comment.
//   - Like DingTalk, business errors are stuffed into the body of an HTTP 200
//     (code != 0).
//   - Card headers support color templates; mapping severity to colors lets people
//     spot severity at a glance in the message list.
type feishuChannel struct{}

func (feishuChannel) Kind() string { return KindFeishu }

// Feishu custom bots allow about 5 requests/second, i.e. 100 per minute.
func (feishuChannel) DefaultRatePerMin() int { return 100 }

// The last segment of the webhook URL is the bot's unique identifier and counts
// as a credential.
func (feishuChannel) SecretKeys() []string { return []string{"webhook", "secret"} }

// Likewise: changing the webhook URL requires re-declaring the signing secret for
// the new address.
func (feishuChannel) DestinationKeys() []string { return []string{"webhook"} }

func (feishuChannel) Validate(cfg map[string]any) error {
	hook := cfgString(cfg, "webhook")
	if hook == "" {
		return errors.New("missing Webhook URL")
	}
	if err := validateHTTPURL(hook); err != nil {
		return fmt.Errorf("invalid webhook URL: %w", err)
	}
	return nil
}

func (c feishuChannel) Send(ctx context.Context, cfg map[string]any, m Message) (int, error) {
	if err := c.Validate(cfg); err != nil {
		return 0, Permanent(err)
	}
	card, kept := feishuCard(m)
	payload := map[string]any{
		"msg_type": "interactive",
		"card":     card,
	}
	// Signing parameters sit at the same level as the message, and appear only
	// when a secret is configured.
	if secret := cfgString(cfg, "secret"); secret != "" {
		ts := strconv.FormatInt(time.Now().Unix(), 10)
		payload["timestamp"] = ts
		payload["sign"] = feishuSign(ts, secret)
	}
	raw, err := doJSON(ctx, "POST", cfgString(cfg, "webhook"), nil, payload)
	if err != nil {
		return 0, err
	}
	var res struct {
		Code int    `json:"code"`
		Msg  string `json:"msg"`
		// Some versions of the Feishu hook use this set of field names; support both.
		StatusCode    int    `json:"StatusCode"`
		StatusMessage string `json:"StatusMessage"`
	}
	if err := json.Unmarshal(raw, &res); err != nil {
		return 0, fmt.Errorf("failed to parse Feishu response: %w (%s)", err, snippet(raw))
	}
	if res.Code != 0 {
		return 0, Permanent(fmt.Errorf("Feishu returned error %d: %s", res.Code, res.Msg))
	}
	if res.StatusCode != 0 {
		return 0, Permanent(fmt.Errorf("Feishu returned error %d: %s", res.StatusCode, res.StatusMessage))
	}
	return kept, nil
}

// feishuSign computes the signature per Feishu's official rules.
//
// This is especially easy to get wrong: the official sample is
//
//	hmac.new(string_to_sign.encode(), digestmod=sha256)
//
// That is, **key = timestamp + "\n" + secret, with an empty message** — not the
// intuitive "key=secret, message=stringToSign", which is exactly DingTalk's
// algorithm. The two algorithms are mirror images of each other, and copying the
// other platform's implementation always fails signature verification (error
// 19021).
func feishuSign(timestamp, secret string) string {
	stringToSign := timestamp + "\n" + secret
	mac := hmac.New(sha256.New, []byte(stringToSign))
	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}

// feishuSeverityTemplate maps vulnerability severity to a card header color
// template. Unknown severities use grey — not blue, to avoid confusion with low.
func feishuSeverityTemplate(severity string) string {
	switch severity {
	case "critical":
		return "red"
	case "high":
		return "orange"
	case "medium":
		return "yellow"
	case "low":
		return "blue"
	default:
		return "grey"
	}
}

// feishuMaxCardBytes is a conservative cap on card content. Feishu custom bots
// reject a request body over 20 KB as a whole (not truncated); pick a value
// clearly below that limit to also cover JSON wrapping overhead.
const feishuMaxCardBytes = 16000

// feishuEnvelopeBytes is the size of what Send serializes around the card when a
// signing secret is configured (without one the request is smaller):
//
//	{"card":…,"msg_type":"interactive","sign":"<44 characters>","timestamp":"<10 digits>"}
const feishuEnvelopeBytes = 113

// feishuCard builds the interactive card and returns it along with the **number
// of items actually written**. kept serves the same purpose as in markdownBody:
// only items that actually made it into the card should be marked as sent.
func feishuCard(m Message) (map[string]any, int) {
	lim := m.limits()
	// budget is the final truncation backstop for one item's text, the same role
	// TruncateBytes plays in markdownBody. With the summary or asset limit set to
	// 0 an item has no other bound, and an oversized card loses the whole message.
	budget := feishuMaxCardBytes - markdownReservedBytes
	card := map[string]any{
		"config": map[string]any{"wide_screen_mode": true},
		"header": map[string]any{"title": map[string]any{"tag": "plain_text", "content": markdownTitle(m)}},
	}
	if len(m.Items) > 0 {
		card["header"].(map[string]any)["template"] = feishuSeverityTemplate(m.Items[0].Severity)
	}
	elements := []any{}
	kept := 0
	if m.Batch {
		// digest assembles the elements of a digest card around the lines of its
		// first n items. The intro must state "the remaining N items will continue
		// in the next message", and N must come from the number of items that
		// actually fit.
		digest := func(n int, lines []any) []any {
			out := []any{feishuMarkdownDiv(markdownBatchIntro(m, m.Items[:n], len(m.Items)))}
			out = append(out, lines...)
			if m.HomeURL != "" {
				out = append(out, feishuButton("View all on the platform", m.HomeURL))
			}
			return out
		}
		// Pack whole items (see packItemCount) against the request body as it will
		// be serialized, not against the text of the lines. Each line is sent as
		// its own element: about 52 bytes of JSON around the text, plus whatever
		// the encoding escapes. Counted as text alone, several hundred short lines
		// left as one request of more than twice the 20 KB limit. The rest of the
		// body is measured too: it changes with the number of items kept (the
		// intro) and with the platform link.
		//
		// The first item is always kept: otherwise one oversized item would jam
		// the whole batch in place. Its text is truncated to budget.
		var lines []any
		used := 0
		for i, it := range m.Items {
			line := feishuMarkdownDiv(TruncateBytes(feishuBatchLine(it, i+1, lim), budget))
			used += feishuJSONSize(line) + 1 // the element and its separating comma
			card["elements"] = digest(i+1, nil)
			if i > 0 && feishuEnvelopeBytes+feishuJSONSize(card)+used > feishuMaxCardBytes {
				break
			}
			lines = append(lines, line)
		}
		kept = len(lines)
		elements = digest(kept, lines)
	} else if len(m.Items) > 0 {
		kept = 1
		it := m.Items[0]
		elements = append(elements, feishuMarkdownDiv(TruncateBytes(feishuItemLines(it, lim), budget)))
		if it.DetailURL != "" {
			elements = append(elements, feishuButton("View details", it.DetailURL))
		}
	}

	card["elements"] = elements
	return card, kept
}

// feishuJSONSize returns the number of bytes v takes in the request body.
func feishuJSONSize(v any) int {
	raw, _ := json.Marshal(v)
	return len(raw)
}

func feishuMarkdownDiv(content string) map[string]any {
	return map[string]any{"tag": "div", "text": map[string]any{"tag": "lark_md", "content": content}}
}

func feishuButton(label, url string) map[string]any {
	return map[string]any{
		"tag": "action",
		"actions": []any{map[string]any{
			"tag":  "button",
			"text": map[string]any{"tag": "lark_md", "content": label},
			"url":  url,
			"type": "primary",
		}},
	}
}

// feishuItemLines renders the lark_md body of a single vulnerability.
//
// lark_md and markdown are sibling text formats that also parse links and
// emphasis, so every field coming from outside goes through markdownText
// (single-lining + escaping) — otherwise a single vulnerability title could turn
// into a clickable external link inside Feishu.
func feishuItemLines(it Item, lim Limits) string {
	out := fmt.Sprintf("**%s · %s**", SeverityLabel(it.Severity), markdownText(it.Title(), 0))
	if it.IsStatusChange() {
		out += fmt.Sprintf("\n**Status change**: %s → %s",
			markdownText(StatusLabel(it.FromStatus), 0), markdownText(StatusLabel(it.ToStatus), 0))
	}
	if it.VulnClass != "" && it.VulnClass != it.Title() {
		out += fmt.Sprintf("\n**Type**: %s", markdownText(it.VulnClass, 0))
	}
	if a := assetLine(it.Assets, lim.AssetsShown); a != "" {
		out += fmt.Sprintf("\n**Assets**: %s", markdownText(a, 0))
	}
	if it.Summary != "" {
		if s := markdownText(it.Summary, lim.SummaryRunes); s != "" {
			out += fmt.Sprintf("\n**Summary**: %s", s)
		}
	}
	return out
}

// feishuBatchLine renders one entry of a digest card.
func feishuBatchLine(it Item, index int, lim Limits) string {
	line := fmt.Sprintf("**%d. %s · %s**", index, SeverityLabel(it.Severity), markdownText(it.Title(), 0))
	if a := assetLine(it.Assets, lim.AssetsShown); a != "" {
		line += " — " + markdownText(a, 0)
	}
	return line
}