feat: implement console module

Author: vthib

Cargo.lock

@@ -23,6 +23,7 @@ object = { git = 'https://github.com/vthib/boreal-object', branch = "version-0.3
 
 # yara-rust:
 # - Add ScanFlags::PROCESS_MEMORY: https://github.com/Hugal31/yara-rust/pull/130
+# - Add CallbackMsg::ConsoleLog: https://github.com/Hugal31/yara-rust/pull/139
 # yara:
 # - Add base address to elf entrypoint: https://github.com/VirusTotal/yara/pull/1989
 # - Fixes for macho module and process memory: https://github.com/VirusTotal/yara/pull/1995

Cargo.toml

@@ -136,6 +136,10 @@ fn main() -> ExitCode {
         #[cfg(not(feature = "authenticode"))]
         let mut compiler = Compiler::new();
 
+        let _r = compiler.add_module(boreal::module::Console::with_callback(Box::new(|log| {
+            println!("{log}");
+        })));
+
         compiler.set_params(
             boreal::compiler::CompilerParams::default()
                 .fail_on_warnings(args.get_flag("fail_on_warnings"))

boreal-cli/src/main.rs

@@ -594,6 +594,7 @@ rule a {
         .stderr("")
         .success();
 }
+
 // Test when some inputs in a dir cannot be read
 #[test]
 #[cfg(unix)]
@@ -675,3 +676,28 @@ rule second {
         .stderr("")
         .success();
 }
+
+#[test]
+fn test_console_log() {
+    let rule_file = test_file(
+        r#"
+import "console"
+
+rule logger {
+    condition:
+        console.log("this is ", "a log")
+}"#,
+    );
+
+    let input = test_file("");
+    cmd()
+        .arg(rule_file.path())
+        .arg(input.path())
+        .assert()
+        .stdout(predicate::eq(format!(
+            "this is a log\nlogger {}\n",
+            input.path().display()
+        )))
+        .stderr("")
+        .success();
+}

boreal-cli/tests/cli.rs

@@ -123,14 +123,14 @@ free. If however someone can provide a valid use-case, this difference can be re
   - `pe.imphash()` is behind the _hash_ feature
 - [x] string
 - [x] time
+- [x] console
 
 Modules not yet supported:
 
 - [ ] cuckoo
 - [ ] dex
 - [ ] dotnet
 - [ ] magic
-- [ ] console
 
 ## Missing Features
 

boreal/README.md

@@ -86,13 +86,16 @@ struct ImportedModule {
 impl Compiler {
     /// Create a new object to compile YARA rules.
     ///
-    /// Almost available modules are enabled by default:
+    /// Modules enabled by default:
     /// - `time`
     /// - `math`
     /// - `string`
     /// - `hash` if the `hash` feature is enabled
     /// - `elf`, `macho` and `pe` if the `object` feature is enabled
     ///
+    /// Modules disabled by default:
+    /// - `console`
+    ///
     /// However, the pe module does not include signatures handling. To include it, you should have
     /// the `authenticode` feature enabled, and use [`Compiler::new_with_pe_signatures`]
     ///

boreal/src/compiler/mod.rs

@@ -0,0 +1,123 @@
+use std::fmt::Write;
+use std::{collections::HashMap, sync::Arc};
+
+use super::{EvalContext, Module, ModuleData, ModuleDataMap, StaticValue, Type, Value};
+
+/// `console` module.
+pub struct Console {
+    callback: Arc<Box<LogCallback>>,
+}
+
+/// Type of callback called when a message is logged.
+pub type LogCallback = dyn Fn(String) + Send + Sync;
+
+impl Module for Console {
+    fn get_name(&self) -> &'static str {
+        "console"
+    }
+
+    fn get_static_values(&self) -> HashMap<&'static str, StaticValue> {
+        [
+            (
+                "log",
+                StaticValue::function(
+                    Self::log,
+                    vec![
+                        vec![Type::Bytes],
+                        vec![Type::Bytes, Type::Bytes],
+                        vec![Type::Integer],
+                        vec![Type::Bytes, Type::Integer],
+                        vec![Type::Float],
+                        vec![Type::Bytes, Type::Float],
+                    ],
+                    Type::Integer,
+                ),
+            ),
+            (
+                "hex",
+                StaticValue::function(
+                    Self::hex,
+                    vec![vec![Type::Integer], vec![Type::Bytes, Type::Integer]],
+                    Type::Integer,
+                ),
+            ),
+        ]
+        .into()
+    }
+
+    fn setup_new_scan(&self, data_map: &mut ModuleDataMap) {
+        data_map.insert::<Self>(Data {
+            callback: Arc::clone(&self.callback),
+        });
+    }
+}
+
+pub struct Data {
+    callback: Arc<Box<LogCallback>>,
+}
+
+impl ModuleData for Console {
+    type Data = Data;
+}
+
+impl Console {
+    /// Create a new console module with a callback.
+    ///
+    /// The callback will be called when expressions using this module
+    /// are used.
+    #[must_use]
+    pub fn with_callback(callback: Box<LogCallback>) -> Self {
+        Self {
+            callback: Arc::new(callback),
+        }
+    }
+
+    fn log(ctx: &mut EvalContext, args: Vec<Value>) -> Option<Value> {
+        let mut args = args.into_iter();
+        let mut res = String::new();
+        add_value(args.next()?, &mut res)?;
+        if let Some(arg) = args.next() {
+            add_value(arg, &mut res)?;
+        }
+
+        let data = ctx.module_data.get::<Console>()?;
+        (data.callback)(res);
+
+        Some(Value::Integer(1))
+    }
+
+    fn hex(ctx: &mut EvalContext, args: Vec<Value>) -> Option<Value> {
+        let mut args = args.into_iter();
+        let res = match args.next()? {
+            Value::Integer(v) => format!("0x{v:x}"),
+            value => {
+                let mut res = String::new();
+                add_value(value, &mut res)?;
+                let v: i64 = args.next()?.try_into().ok()?;
+                write!(&mut res, "0x{v:x}").ok()?;
+                res
+            }
+        };
+
+        let data = ctx.module_data.get::<Console>()?;
+        (data.callback)(res);
+
+        Some(Value::Integer(1))
+    }
+}
+
+fn add_value(value: Value, out: &mut String) -> Option<()> {
+    match value {
+        Value::Integer(v) => write!(out, "{v}").ok(),
+        Value::Float(v) => write!(out, "{v}").ok(),
+        Value::Bytes(v) => {
+            for byte in v {
+                for b in std::ascii::escape_default(byte) {
+                    out.push(char::from(b));
+                }
+            }
+            Some(())
+        }
+        _ => None,
+    }
+}

boreal/src/module/console.rs

@@ -44,6 +44,9 @@ use std::sync::Arc;
 use crate::memory::{Memory, Region};
 use crate::regex::Regex;
 
+mod console;
+pub use console::{Console, LogCallback};
+
 mod time;
 pub use time::Time;
 

boreal/src/module/mod.rs

@@ -1,4 +1,6 @@
-use crate::utils::{check, check_boreal, check_err};
+use std::sync::Mutex;
+
+use crate::utils::{check, check_boreal, check_err, Compiler};
 
 #[track_caller]
 fn check_tests_err(condition: &str, expected_err: &str) {
@@ -441,6 +443,71 @@ fn test_module_hash() {
     test("not defined hash.crc32(100, 2)");
 }
 
+#[test]
+fn test_module_console() {
+    static LOGS: Mutex<Vec<String>> = Mutex::new(Vec::new());
+    let mut compiler = Compiler::new();
+    let res = compiler
+        .compiler
+        .add_module(boreal::module::Console::with_callback(Box::new(|log| {
+            LOGS.lock().unwrap().push(log);
+        })));
+    assert!(res);
+
+    compiler.add_rules(
+        r#"import "console"
+rule a {
+    condition:
+        console.log("a\n\xBAc\x00-") and
+        console.log("bytes: ", "bo\tr") and
+        console.log(15) and
+        console.log("value", 15) and
+        console.log(3.59231) and
+        console.log("float: ", 015.340) and
+        console.log("", "bar") and
+        console.hex(12872) and
+        console.hex("val: ", -12872) and
+        false and
+        console.log("missing")
+
+}"#,
+    );
+
+    let mut checker = compiler.into_checker();
+    checker.check(b"", false);
+
+    assert_eq!(
+        &*LOGS.lock().unwrap(),
+        &[
+            r"a\n\xbac\x00-",
+            r"bytes: bo\tr",
+            "15",
+            "value15",
+            "3.59231",
+            "float: 15.34",
+            "bar",
+            "0x3248",
+            "val: 0xffffffffffffcdb8",
+        ]
+    );
+
+    let yara_logs = checker.capture_yara_logs(b"");
+    assert_eq!(
+        yara_logs,
+        &[
+            r"a\x0a\xbac\x00-",
+            r"bytes: bo\x09r",
+            "15",
+            "value15",
+            "3.592310",
+            "float: 15.340000",
+            "bar",
+            "0x3248",
+            "val: 0xffffffffffffcdb8",
+        ]
+    );
+}
+
 #[test]
 fn test_module_iterable_imbricated() {
     check_ok(

boreal/tests/it/modules.rs

@@ -15,7 +15,7 @@ pub struct Checker {
 }
 
 pub struct Compiler {
-    compiler: boreal::Compiler,
+    pub compiler: boreal::Compiler,
     yara_compiler: Option<yara::Compiler>,
 }
 
@@ -473,6 +473,24 @@ impl Checker {
             yara_scanner: self.yara_rules.as_ref().map(|v| v.scanner().unwrap()),
         }
     }
+
+    pub fn capture_yara_logs(&mut self, mem: &[u8]) -> Vec<String> {
+        let mut logs = Vec::new();
+
+        let Some(rules) = &mut self.yara_rules else {
+            return logs;
+        };
+
+        rules
+            .scan_mem_callback(mem, 0, |msg| {
+                if let yara::CallbackMsg::ConsoleLog(log) = msg {
+                    logs.push(log.to_string_lossy().to_string());
+                }
+                yara::CallbackReturn::Continue
+            })
+            .unwrap();
+        logs
+    }
 }
 
 #[derive(Debug)]