rspamd-shiki-grammars

Shiki syntax highlighting grammars for Rspamd map file formats.

Grammars

Language name	Format
rspamd-map	Plain and key-value maps
rspamd-radix-map	IP/network (radix) maps
rspamd-regexp-map	Regular expression maps
rspamd-sa-rules	SpamAssassin-style rule files
rspamd-composites	Composite symbol definitions

Installation

npm install rspamd-shiki-grammars

Requires shiki >= 1.0 as a peer dependency.

Usage

Register all grammars at once

import { createHighlighter } from 'shiki'
import { rspamdGrammars } from 'rspamd-shiki-grammars'

const hl = await createHighlighter({
  langs: rspamdGrammars,
  themes: ['github-dark'],
})

const html = hl.codeToHtml(mapContent, {
  lang: 'rspamd-sa-rules',
  theme: 'github-dark',
})

Register individual grammars

import { createHighlighter } from 'shiki'
import {
  rspamdMapGrammar,
  rspamdRadixMapGrammar,
  rspamdRegexpMapGrammar,
  rspamdSaRulesGrammar,
} from 'rspamd-shiki-grammars'

const hl = await createHighlighter({
  langs: [rspamdMapGrammar, rspamdRadixMapGrammar],
  themes: ['nord'],
})

With @shikijs/react (or any Shiki-based React library)

import { codeToHtml } from 'shiki'
import { rspamdGrammars } from 'rspamd-shiki-grammars'

export async function MapViewer({ code }: { code: string }) {
  const html = await codeToHtml(code, {
    lang: 'rspamd-map',
    theme: 'github-light',
    langs: rspamdGrammars,
  })
  return <div dangerouslySetInnerHTML={{ __html: html }} />
}

Map format overview

rspamd-map — plain and key-value maps

Lines are either a bare key, a key value pair, or a comment. Quoted keys ("key with spaces") are supported.

# blocklist
spammer.example.com
"quoted domain.com"
trusted.host   allowlisted

rspamd-radix-map — IP/network maps

Keys are IPv4 or IPv6 addresses and CIDR prefixes. Multiple addresses per line can be comma-separated.

# local networks
10.0.0.0/8
192.168.0.0/16,172.16.0.0/12   internal
2001:db8::/32
[::1]           loopback

rspamd-regexp-map — regular expression maps

Keys are PCRE patterns in any of the forms Rspamd accepts. An optional value follows the pattern.

# Rspamd regexp map
/\bviagra\b/i          drug_spam
/\bclick\s+here\b/iu   clickhere
m{https?://bit\.ly}    shortlink
m!paypal\.com\.ru!i    phishing

Supported pattern flags: i m s x u r O L

rspamd-sa-rules — SpamAssassin-style rules

Supports all directives understood by Rspamd's multimap SA rules parser.

# Drug spam detection
header  DRUG_SUBJ  Subject  =~ /\b(viagra|cialis|levitra)\b/i
rawbody DRUG_BODY  /\b(buy now|order online)\b/i
uri     DRUG_URI   /pills?\.com/i

selector FROM_RU  from.addr  =~ /\.ru$/i

meta     DRUG_COMBO  DRUG_SUBJ && (DRUG_BODY || DRUG_URI)
score    DRUG_COMBO  5.0
describe DRUG_COMBO  Multiple drug spam signals

Directives:

Directive	Syntax
header	header ATOM Header-Name =~ /pattern/flags
body	body ATOM /pattern/flags
rawbody	rawbody ATOM /pattern/flags
uri	uri ATOM /pattern/flags
full	full ATOM /pattern/flags
selector	selector ATOM pipeline =~ /pattern/flags
meta	meta ATOM expr — boolean/arithmetic over atom names
score	score ATOM value
describe	describe ATOM text

rspamd-composites — composite symbol definitions

UCL-style blocks (as used in local.d/composites.conf) defining composite symbols. The expression value is highlighted as the composite expression language: boolean operators, removal-policy prefixes, group references, and symbol options.

# Combine related signals
PHISHING_COMBO {
    expression = "PHISHING & (SUSPICIOUS_URL | REDIRECTOR_URL)";
    score = 8.0;
}

WHITELIST_SENDER {
    expression = "-FORGED_SENDER & g+:fuzzy & DMARC_POLICY_REJECT[sp]";
    score = -10.0;
    policy = "leave";
    enabled = true;
}

Expression language elements:

Element	Syntax
Boolean operators	& | !, or and or not (any case)
Grouping	( ... )
Removal-policy prefix	~SYMBOL (keep weight), -SYMBOL (keep both), ^SYMBOL (force remove)
Group reference	g:name, g+:name, g-:name
Symbol options	SYMBOL[opt1,opt2], SYMBOL[/regex/i, opt]

Block properties: expression, score, group, policy, enabled, description.

Development

npm run build      # compile to dist/
npm test           # run 114 Vitest unit tests
npm run test:watch # watch mode

Tests assert TextMate scope names directly via Shiki's includeExplanation API, so grammar regressions are caught at the token level.

License

Apache 2.0 — see LICENSE.