🥮 mooncakes.io

termproof

Streaming ANSI/ECMA-48 terminal log sanitizer and security auditor for MoonBit

ansi
terminal
security
logs
ci
moon add DWS-ai-nb/termproof@0.1.0
Download zip
Author
Version
0.1.0
License
MIT
Repository
Last updated
14 hours ago
Downloads
3
README

#TermProof

TermProof is a MoonBit library and command-line tool for auditing untrusted terminal logs before they are shown in CI, issue trackers, release notes, or chat systems.

Repository: https://github.com/DWS-ai-nb/moonbit-readme-ci-mooncakes-io-git-10

Terminal output is not plain text. ANSI/ECMA-48 control sequences can move the cursor, erase history, rewrite previous lines, set deceptive hyperlinks, write to the clipboard, or hide filenames with Unicode bidirectional controls. TermProof turns that output into deterministic text and a security report.

#Why This Project Is Different

Most terminal packages help programs produce nicer output. TermProof looks at the opposite side: it treats terminal output as hostile input. The project focuses on log integrity, reproducible auditing, and safe rendering instead of colors, TUIs, progress bars, or shell helpers.

#Features

  • Streaming ECMA-48 parser that handles split ESC, CSI, OSC, DCS, SOS, PM, and APC sequences.
  • Classification for cursor movement, screen erase, terminal queries, title changes, OSC 8 hyperlinks, OSC 52 clipboard writes, iTerm-style file transfer extensions, notifications, and device-control strings.
  • Unicode bidirectional-control detection for Trojan Source style filename or source-code disguise.
  • Four built-in policies: strict, ci, plain, and permissive.
  • Safe outputs: plain_text, safe_terminal, JSON, Markdown, and GitHub Actions annotations.
  • CLI commands for auditing, cleaning, event dumps, and a built-in demo.
  • Original fixtures and unit tests. No third-party log corpus is bundled.

#Installation

Install from mooncakes.io:

moon add DWS-ai-nb/termproof

Import the library from another package:

import {
  "DWS-ai-nb/termproof" @termproof
}

#Quick Start

fn main {
  let log = "ok\u{1b}[32mPASS\u{1b}[0m\n" +
    "copy\u{1b}]52;c;SGVsbG8=\u{7}\n"
  let result = @termproof.audit(log, policy=@termproof.Policy::strict())
  println(@termproof.summary_line(result))
  println(result.plain_text)
}

#CLI

Run the built-in example:

moon run cmd/termproof -- demo

Audit text and fail when the selected policy threshold is reached:

moon run cmd/termproof -- audit "trusted output" --policy strict

Write a Markdown report:

moon run cmd/termproof -- audit "trusted output" --format markdown

Clean text for display:

moon run cmd/termproof -- clean "trusted output" --policy plain

Emit parser events for debugging:

moon run cmd/termproof -- events "trusted output"

#Policies

PolicyIntended useKeeps SGR colorsKeeps OSC 8 linksMarks dangerous dataFails at
strictreview and artifact publishingnonoyesdangerous
ciCI logs that may keep colorsyesnonocritical
plainirreversible text exportnononocritical
permissivediagnostics and migrationyesyes, except high-risk schemesnocritical

#Supported Scope

TermProof is intentionally narrow. It parses terminal-control syntax and classifies security-relevant behavior in logs. It does not emulate a full terminal, execute shell commands, render a TUI, or validate every terminal-specific private extension. Unknown and malformed controls are still reported and removed according to policy.

#Development

moon check --deny-warn
moon fmt --check
moon build
moon test --deny-warn
moon run examples/audit
moon run cmd/termproof -- audit "trusted output" --policy strict
moon info
moon package --list

The GitHub Actions workflow runs the same checks on every push and pull request. The default target is wasm-gc, so the project can build and test without requiring a local C compiler.

#Publishing

The module metadata in moon.mod is ready for mooncakes.io. Before publishing, confirm that dws-ai-nb matches the actual mooncakes.io owner, then run:

moon login
moon package --list
moon publish --frozen

Mooncakes uses the README and metadata from moon.mod for the package page, so both are kept as part of the release surface.

#License

TermProof is released under the MIT License. See LICENSE and THIRD_PARTY_NOTICES.md.

#
AuditResult

source
pub(all) struct AuditResult {
  plain_text : String
  safe_terminal : String
  events : Array[Event]
  findings : Array[Finding]
  stats : Stats
  failed : Bool
} derive(Eq, 
Debug)

Full result returned by audit.

#
CsiCommand

source
pub(all) struct CsiCommand {
  private_prefix : String
  params : Array[Int?]
  intermediates : String
  final_byte : Char
} derive(Eq, 
Debug)

Parsed view of a CSI payload. Missing parameters are represented as None; this preserves the semantic difference between an omitted value and zero.

#
Decision

source
pub(all) enum Decision {
  Keep
  Drop
  Mark
} derive(Eq, 
Debug)

Action selected by a policy for an event.

#
Event

source
pub(all) struct Event {
  kind : EventKind
  raw : String
  payload : String
  final_byte : Char?
  offset : Int
  complete : Bool
} derive(Eq, 
Debug)

One event emitted by the streaming parser.

raw contains the original sequence, payload omits introducers and terminators, and final_byte is set for CSI/ESC commands that have one.

#
EventKind

source
pub(all) enum EventKind {
  Text
  C0
  Escape
  Csi
  Osc
  Dcs
  Sos
  Pm
  Apc
  C1
  Invalid
  Truncated
} derive(Eq, 
Debug)

Broad syntactic family of an ECMA-48 event.

#
Finding

source
pub(all) struct Finding {
  rule_id : String
  severity : Severity
  risk : RiskKind
  message : String
  offset : Int
  sequence : String
  decision : Decision
} derive(Eq, 
Debug)

A human-readable security finding tied to an event offset.

#
OscCommand

source
pub(all) struct OscCommand {
  command : String
  data : String
} derive(Eq, 
Debug)

Parsed view of an OSC event.

#
Parser

source
pub(all) struct Parser {
  mode : ParserMode
  text : Array[Char]
  sequence : Array[Char]
  payload : Array[Char]
  sequence_start : Int
  offset : Int
}

Incremental ECMA-48 parser. It accepts arbitrary chunk boundaries, including a split between ESC and \\ in an ST terminator.

#
Parser::consumed

source
fn Parser::consumed(self : Parser) -> Int

#
Parser::current_mode

source
fn Parser::current_mode(self : Parser) -> ParserMode

#
Parser::feed

source
fn Parser::feed(self : Parser, chunk : String) -> Array[Event]

Feed a chunk and return all events completed by that chunk. Text is held until a control boundary or finish, so adjacent chunks coalesce naturally.

#
Parser::finish

source
fn Parser::finish(self : Parser) -> Array[Event]

Flush remaining text and turn an unfinished control string into a Truncated event. Calling finish resets the parser to Ground and is idempotent.

#
Parser::new

source
fn Parser::new() -> Parser

#
ParserMode

source
pub(all) enum ParserMode {
  Ground
  EscapeStart
  EscapeIntermediate
  CsiEntry
  CsiParam
  CsiIntermediate
  OscString
  OscEscape
  DcsString
  DcsEscape
  SosString
  SosEscape
  PmString
  PmEscape
  ApcString
  ApcEscape
} derive(Eq, 
Debug)

Parser mode that is exposed so callers can inspect streaming state.

#
Policy

source
pub(all) struct Policy {
  name : String
  keep_sgr : Bool
  keep_hyperlinks : Bool
  keep_bell : Bool
  mark_dangerous : Bool
  remove_bidi : Bool
  fail_at : Severity
  unknown_severity : Severity
  max_sequence_chars : Int
} derive(Eq, 
Debug)

Sanitization and CI failure policy.

#
Policy::ci

source
fn Policy::ci() -> Policy

#
Policy::permissive

source
fn Policy::permissive() -> Policy

#
Policy::plain

source
fn Policy::plain() -> Policy

#
Policy::strict

source
fn Policy::strict() -> Policy

#
RiskKind

source
pub(all) enum RiskKind {
  Styling
  CursorMovement
  ScreenRewrite
  ScreenErase
  TerminalQuery
  ModeChange
  TitleChange
  Hyperlink
  ClipboardWrite
  Notification
  WorkingDirectory
  FileTransfer
  DeviceControl
  BidirectionalText
  UnknownControl
  MalformedSequence
} derive(Eq, 
Debug)

Security-relevant behavior inferred from a control sequence.

#
Severity

source
pub(all) enum Severity {
  Info
  Warning
  Dangerous
  Critical
} derive(Compare, Eq, 
Debug)

Severity assigned to a terminal-control finding.

#
Stats

source
pub(all) struct Stats {
  input_chars : Int
  text_chars : Int
  control_events : Int
  info : Int
  warnings : Int
  dangerous : Int
  critical : Int
  dropped : Int
  marked : Int
} derive(Eq, 
Debug)

Summary counters for an audit run.

#
audit

source
fn audit(input : String, policy? : Policy) -> AuditResult

Parse, classify, and sanitize terminal output according to policy.

plain_text never contains terminal controls. safe_terminal may retain SGR or OSC 8 only when explicitly allowed by the selected policy.

#
classify

source
fn classify(event : Event, policy : Policy) -> Finding?

#
contains_char

source
fn contains_char(input : String, needle : Char) -> Bool

#
csi_param

source
fn csi_param(command : CsiCommand, index : Int, default : Int) -> Int

#
event_kind_name

source
fn event_kind_name(kind : EventKind) -> String

#
github_message_escape

source
fn github_message_escape(input : String) -> String

#
github_property_escape

source
fn github_property_escape(input : String) -> String

GitHub workflow command escaping as documented for annotation properties.

#
has_terminal_controls

source
fn has_terminal_controls(input : String) -> Bool

#
is_bidi_control

source
fn is_bidi_control(c : Char) -> Bool

#
is_suspicious_uri

source
fn is_suspicious_uri(uri : String) -> Bool

#
json_quote

source
fn json_quote(input : String) -> String

#
lower_ascii

source
fn lower_ascii(input : String) -> String

#
markdown_escape

source
fn markdown_escape(input : String) -> String

#
parse

source
fn parse(input : String) -> Array[Event]

Convenience batch parser.

#
parse_csi

source
fn parse_csi(event : Event) -> CsiCommand?

#
parse_osc

source
fn parse_osc(event : Event) -> OscCommand?

#
policy_named

source
fn policy_named(name : String) -> Policy?

#
report_github_annotations

source
fn report_github_annotations(result : AuditResult, file? : String) -> String

#
report_json

source
fn report_json(result : AuditResult, include_events? : Bool) -> String

Deterministic JSON report with no dependency on a JSON serialization package.

#
report_markdown

source
fn report_markdown(result : AuditResult) -> String

#
risk_name

source
fn risk_name(risk : RiskKind) -> String

#
sanitize

source
fn sanitize(input : String) -> String

#
sanitize_for_ci

source
fn sanitize_for_ci(input : String) -> String

#
severity_name

source
fn severity_name(severity : Severity) -> String

#
severity_rank

source
fn severity_rank(severity : Severity) -> Int

#
starts_with_ascii_case_insensitive

source
fn starts_with_ascii_case_insensitive(input : String, prefix : String) -> Bool

#
strip_bidi_controls

source
fn strip_bidi_controls(input : String) -> String

#
summary_line

source
fn summary_line(result : AuditResult) -> String

#
visible

source
fn visible(input : String) -> String

Render non-printing characters as stable ASCII. The result is safe to paste into terminals and useful in audit reports.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io