Add Rust format string provider API

plafosse · plafosse · commit a2889f3faaa5 · 2026-08-02T08:55:47.000-04:00
diff --git a/rust/src/format_string_resolution_provider.rs b/rust/src/format_string_resolution_provider.rs
@@ -0,0 +1,219 @@
+//! APIs for resolving argument types described by format strings.
+
+use binaryninjacore_sys::*;
+use std::ffi::{c_char, c_void};
+use std::fmt::Debug;
+use std::ptr::NonNull;
+
+use crate::confidence::Conf;
+use crate::platform::Platform;
+use crate::rc::{Array, CoreArrayProvider, CoreArrayProviderInner, Ref};
+use crate::string::{raw_to_string, BnString, IntoCStr};
+use crate::types::Type;
+
+/// A custom provider that validates format strings and resolves their argument types.
+///
+/// Providers are registered for the lifetime of the process and may be invoked from multiple
+/// analysis threads.
+pub trait CustomFormatStringResolutionProvider: Send + Sync + 'static {
+    /// Resolve the argument types described by `format` for `platform`.
+    ///
+    /// Return `None` when the string is not valid for this provider. A valid string with no
+    /// arguments is represented by `Some(Vec::new())`. Each returned type retains its individual
+    /// confidence value.
+    fn is_valid(&self, format: &str, platform: Option<&Platform>) -> Option<Vec<Conf<Ref<Type>>>>;
+}
+
+/// A registered format string resolution provider.
+#[derive(Clone, Copy, Hash, PartialEq, Eq)]
+#[repr(transparent)]
+pub struct FormatStringResolutionProvider {
+    handle: NonNull<BNFormatStringResolutionProvider>,
+}
+
+impl FormatStringResolutionProvider {
+    pub(crate) unsafe fn from_raw(handle: NonNull<BNFormatStringResolutionProvider>) -> Self {
+        Self { handle }
+    }
+
+    /// Register a custom format string resolution provider.
+    ///
+    /// The provider is retained for the lifetime of the process.
+    pub fn register<P>(name: &str, provider: P) -> Self
+    where
+        P: CustomFormatStringResolutionProvider,
+    {
+        let name = name.to_cstr();
+        // The core registry has no unregister operation, so the callback context must remain valid
+        // for the lifetime of the process.
+        let provider = Box::leak(Box::new(provider));
+        let mut callbacks = BNFormatStringResolutionProviderCallbacks {
+            context: provider as *mut P as *mut c_void,
+            isValid: Some(cb_is_valid::<P>),
+            freeTypeList: Some(cb_free_type_list),
+        };
+        let result =
+            unsafe { BNRegisterFormatStringResolutionProvider(name.as_ptr(), &mut callbacks) };
+        let handle =
+            NonNull::new(result).expect("failed to register format string resolution provider");
+        unsafe { Self::from_raw(handle) }
+    }
+
+    /// Retrieve all registered format string resolution providers.
+    pub fn all() -> Array<Self> {
+        let mut count = 0;
+        let result = unsafe { BNGetFormatStringResolutionProviderList(&mut count) };
+        assert!(!result.is_null());
+        unsafe { Array::new(result, count, ()) }
+    }
+
+    /// Retrieve a registered format string resolution provider by name.
+    pub fn by_name(name: &str) -> Option<Self> {
+        let name = name.to_cstr();
+        let result = unsafe { BNGetFormatStringResolutionProviderByName(name.as_ptr()) };
+        NonNull::new(result).map(|handle| unsafe { Self::from_raw(handle) })
+    }
+
+    /// Return the provider's registration name.
+    pub fn name(&self) -> String {
+        let result = unsafe { BNGetFormatStringResolutionProviderName(self.handle.as_ptr()) };
+        assert!(!result.is_null());
+        unsafe { BnString::into_string(result) }
+    }
+
+    /// Resolve the argument types described by `format` for `platform`.
+    ///
+    /// Return `None` when the string is not valid for this provider. A valid string with no
+    /// arguments is represented by `Some(Vec::new())`.
+    pub fn is_valid(
+        &self,
+        format: &str,
+        platform: Option<&Platform>,
+    ) -> Option<Vec<Conf<Ref<Type>>>> {
+        let format = format.to_cstr();
+        let mut types = std::ptr::null_mut();
+        let mut count = 0;
+        let valid = unsafe {
+            BNFormatStringResolutionProviderIsValid(
+                self.handle.as_ptr(),
+                format.as_ptr(),
+                platform.map_or(std::ptr::null_mut(), |platform| platform.handle),
+                &mut types,
+                &mut count,
+            )
+        };
+
+        if !valid {
+            if !types.is_null() {
+                unsafe { BNFreeTypeWithConfidenceList(types, count) };
+            }
+            return None;
+        }
+
+        if count == 0 {
+            if !types.is_null() {
+                unsafe { BNFreeTypeWithConfidenceList(types, count) };
+            }
+            return Some(Vec::new());
+        }
+
+        if types.is_null() {
+            return None;
+        }
+
+        let result = unsafe { std::slice::from_raw_parts(types, count) }
+            .iter()
+            .map(Conf::<Ref<Type>>::from_raw)
+            .collect();
+        unsafe { BNFreeTypeWithConfidenceList(types, count) };
+        Some(result)
+    }
+}
+
+impl Debug for FormatStringResolutionProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("FormatStringResolutionProvider")
+            .field("name", &self.name())
+            .finish()
+    }
+}
+
+unsafe impl Send for FormatStringResolutionProvider {}
+unsafe impl Sync for FormatStringResolutionProvider {}
+
+impl CoreArrayProvider for FormatStringResolutionProvider {
+    type Raw = *mut BNFormatStringResolutionProvider;
+    type Context = ();
+    type Wrapped<'a> = Self;
+}
+
+unsafe impl CoreArrayProviderInner for FormatStringResolutionProvider {
+    unsafe fn free(raw: *mut Self::Raw, _count: usize, _context: &Self::Context) {
+        BNFreeFormatStringResolutionProviderList(raw);
+    }
+
+    unsafe fn wrap_raw<'a>(raw: &'a Self::Raw, _context: &'a Self::Context) -> Self::Wrapped<'a> {
+        let handle =
+            NonNull::new(*raw).expect("format string resolution provider list contained null");
+        Self::from_raw(handle)
+    }
+}
+
+unsafe extern "C" fn cb_is_valid<P>(
+    ctxt: *mut c_void,
+    format: *const c_char,
+    platform: *mut BNPlatform,
+    types: *mut *mut BNTypeWithConfidence,
+    count: *mut usize,
+) -> bool
+where
+    P: CustomFormatStringResolutionProvider,
+{
+    ffi_wrap!("CustomFormatStringResolutionProvider::is_valid", unsafe {
+        if types.is_null() || count.is_null() {
+            return false;
+        }
+        *types = std::ptr::null_mut();
+        *count = 0;
+
+        let Some(format) = raw_to_string(format) else {
+            return false;
+        };
+        let provider = &*(ctxt as *const P);
+        let platform = NonNull::new(platform).map(|handle| Platform::from_raw(handle.as_ptr()));
+        let Some(result) = provider.is_valid(&format, platform.as_ref()) else {
+            return false;
+        };
+
+        let raw_types: Box<[BNTypeWithConfidence]> = result
+            .into_iter()
+            .map(Conf::<Ref<Type>>::into_raw)
+            .collect();
+        *count = raw_types.len();
+        if raw_types.is_empty() {
+            true
+        } else {
+            *types = Box::leak(raw_types).as_mut_ptr();
+            true
+        }
+    })
+}
+
+unsafe extern "C" fn cb_free_type_list(
+    _ctxt: *mut c_void,
+    types: *mut BNTypeWithConfidence,
+    count: usize,
+) {
+    ffi_wrap!(
+        "CustomFormatStringResolutionProvider::free_type_list",
+        unsafe {
+            if types.is_null() {
+                return;
+            }
+            let types = Box::from_raw(std::ptr::slice_from_raw_parts_mut(types, count));
+            for ty in types {
+                Conf::<Ref<Type>>::free_raw(ty);
+            }
+        }
+    )
+}
diff --git a/rust/src/lib.rs b/rust/src/lib.rs
@@ -53,6 +53,7 @@ pub mod external_library;
 pub mod file_accessor;
 pub mod file_metadata;
 pub mod flowgraph;
+pub mod format_string_resolution_provider;
 pub mod function;
 pub mod function_recognizer;
 pub mod headless;
diff --git a/rust/tests/format_string_resolution_provider.rs b/rust/tests/format_string_resolution_provider.rs
@@ -0,0 +1,97 @@
+use binaryninja::confidence::Conf;
+use binaryninja::format_string_resolution_provider::{
+    CustomFormatStringResolutionProvider, FormatStringResolutionProvider,
+};
+use binaryninja::headless::Session;
+use binaryninja::platform::Platform;
+use binaryninja::rc::Ref;
+use binaryninja::types::Type;
+use serial_test::serial;
+
+struct TestProvider;
+
+impl CustomFormatStringResolutionProvider for TestProvider {
+    fn is_valid(&self, format: &str, platform: Option<&Platform>) -> Option<Vec<Conf<Ref<Type>>>> {
+        match format {
+            "platform" => {
+                let platform = platform?;
+                Some(vec![
+                    Conf::new(Type::int(platform.address_size(), true), 173),
+                    Conf::new(Type::float(8), 91),
+                ])
+            }
+            "empty" => Some(Vec::new()),
+            _ => None,
+        }
+    }
+}
+
+#[test]
+#[serial]
+fn register_list_and_lookup_provider() {
+    let _session = Session::new().expect("Failed to initialize session");
+    let provider = FormatStringResolutionProvider::register(
+        "RustFormatStringResolutionProvider.List",
+        TestProvider,
+    );
+    assert_eq!(provider.name(), "RustFormatStringResolutionProvider.List");
+
+    let provider =
+        FormatStringResolutionProvider::by_name("RustFormatStringResolutionProvider.List")
+            .expect("registered provider is available by name");
+    assert_eq!(provider.name(), "RustFormatStringResolutionProvider.List");
+    assert!(FormatStringResolutionProvider::all()
+        .iter()
+        .any(|candidate| candidate.name() == "RustFormatStringResolutionProvider.List"));
+}
+
+#[test]
+#[serial]
+fn custom_provider_round_trip_preserves_platform_types_and_confidence() {
+    let _session = Session::new().expect("Failed to initialize session");
+    let provider = FormatStringResolutionProvider::register(
+        "RustFormatStringResolutionProvider.RoundTrip",
+        TestProvider,
+    );
+    let platform = Platform::by_name("windows-x86_64").expect("windows-x86_64 exists");
+
+    let types = provider
+        .is_valid("platform", Some(&platform))
+        .expect("format is valid");
+    assert_eq!(types.len(), 2);
+    assert_eq!(types[0].contents.width(), platform.address_size() as u64);
+    assert_eq!(types[0].confidence, 173);
+    assert_eq!(types[1].contents.width(), 8);
+    assert_eq!(types[1].confidence, 91);
+
+    assert!(provider
+        .is_valid("empty", Some(&platform))
+        .expect("empty format is valid")
+        .is_empty());
+    assert!(provider.is_valid("invalid", Some(&platform)).is_none());
+    assert!(provider.is_valid("platform", None).is_none());
+}
+
+#[test]
+#[serial]
+fn native_c_style_provider_is_loaded_in_headless_sessions() {
+    let _session = Session::new().expect("Failed to initialize session");
+    let provider = FormatStringResolutionProvider::by_name("CStyleFormatString")
+        .expect("native C-style provider is loaded without explicit registration");
+    let windows = Platform::by_name("windows-x86_64").expect("windows-x86_64 exists");
+    let linux = Platform::by_name("linux-x86_64").expect("linux-x86_64 exists");
+
+    let windows_types = provider
+        .is_valid("%ld", Some(&windows))
+        .expect("%ld is a valid Windows format string");
+    assert_eq!(windows_types.len(), 1);
+    assert_eq!(windows_types[0].contents.width(), 4);
+    assert_eq!(windows_types[0].confidence, u8::MAX);
+
+    let linux_types = provider
+        .is_valid("%ld", Some(&linux))
+        .expect("%ld is a valid Linux format string");
+    assert_eq!(linux_types.len(), 1);
+    assert_eq!(linux_types[0].contents.width(), 8);
+    assert_eq!(linux_types[0].confidence, u8::MAX);
+}
