initial commit

.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: Unit Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  RUSTFLAGS: "-C target-cpu=native"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          components: clippy
+
+      - name: Run sccache-cache
+        uses: mozilla-actions/[email protected]
+
+      - name: Run clippy
+        run: cargo clippy -- -D warnings
+
+      - name: Run tests
+        run: cargo test

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "lightningscanner"
+description = "A lightning-fast memory pattern scanner, capable of scanning gigabytes of data per second."
+edition = "2021"
+version = "1.0.0"
+authors = ["localcc"]
+license = "MIT"
+keywords = ["memory", "pattern", "reverse-engineering", "game-hacking"]
+categories = ["algorithms"]
+repository = "https://github.com/localcc/lightningscanner-rs"
+
+[dependencies]
+elain = "0.3.0"
+parking_lot = "0.12.1"
+
+[dev-dependencies]
+criterion = "0.5.1"
+tinyrand = "0.5.0"
+
+[[bench]]
+name = "scan_1gb"
+harness = false

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 localcc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,28 @@
+# LightningScanner
+
+A lightning-fast memory pattern scanner, capable of scanning gigabytes of data per second.
+
+## Installation
+
+```
+cargo add lightningscanner
+```
+
+## Examples
+
+Here's an example of how to find an IDA-style memory pattern inside of a binary.
+
+```rust
+
+use lightningscanner::Scanner;
+
+fn main() {
+    let binary = [0xab, 0xec, 0x48, 0x89, 0x5c, 0x24, 0xee, 0x48, 0x89, 0x6c];
+
+    let scanner = Scanner::new("48 89 5c 24 ?? 48 89 6c");
+    let result = scanner.find(None, &binary);
+
+    println!("{:?}", result);
+}
+
+```

benches/scan_1gb.rs

@@ -0,0 +1,53 @@
+use criterion::{criterion_group, criterion_main, Criterion, Throughput};
+use lightningscanner::{ScanMode, Scanner};
+use tinyrand::{Rand, Wyrand};
+
+fn benchmark(c: &mut Criterion) {
+    const GB: usize = 1073741824;
+
+    let mut data = Vec::with_capacity(GB);
+    let mut rand = Wyrand::default();
+    for _ in 0..(GB / 2) {
+        let value = rand.next_u16();
+        data.push((value & 0xff) as u8);
+        data.push(((value >> 8) & 0xff) as u8);
+    }
+
+    const PATTERN_DATA: [u8; 32] = [
+        0x48, 0x89, 0x5C, 0x24, 0x00, 0x48, 0x89, 0x6C, 0x24, 0x00, 0x48, 0x89, 0x74, 0x24, 0x00,
+        0x48, 0x89, 0x7C, 0x24, 0x00, 0x41, 0x56, 0x41, 0x57, 0x4c, 0x8b, 0x79, 0x38, 0xaa, 0xbf,
+        0xcd, 0x00,
+    ];
+
+    let len = data.len();
+    data[len - 32..].copy_from_slice(&PATTERN_DATA);
+
+    let mut group = c.benchmark_group("1gb scan");
+    group.throughput(Throughput::Bytes(GB as u64));
+
+    group.bench_function("scalar", |b| {
+        let scanner = Scanner::new("48 89 5c 24 ?? 48 89 6c 24 ?? 48 89 74 24 ?? 48 89 7c 24 ?? 41 56 41 57 4c 8b 79 38 aa bf cd");
+        b.iter(|| {
+            scanner.find(Some(ScanMode::Scalar), &data)
+        });
+    });
+
+    group.bench_function("sse4.2", |b| {
+        let scanner = Scanner::new("48 89 5c 24 ?? 48 89 6c 24 ?? 48 89 74 24 ?? 48 89 7c 24 ?? 41 56 41 57 4c 8b 79 38 aa bf cd");
+        b.iter(|| {
+            scanner.find(Some(ScanMode::Sse42), &data)
+        });
+    });
+
+    group.bench_function("avx2", |b| {
+        let scanner = Scanner::new("48 89 5c 24 ?? 48 89 6c 24 ?? 48 89 74 24 ?? 48 89 7c 24 ?? 41 56 41 57 4c 8b 79 38 aa bf cd");
+        b.iter(|| {
+            scanner.find(Some(ScanMode::Avx2), &data)
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, benchmark);
+criterion_main!(benches);

src/aligned_bytes.rs

@@ -0,0 +1,88 @@
+//! Aligned byte storage implementation
+
+use elain::{Align, Alignment};
+use std::ops::Deref;
+use std::{alloc, ptr};
+
+#[repr(C)]
+pub struct AlignedBytes<const N: usize>(Align<N>, [u8])
+where
+    Align<N>: Alignment;
+
+#[repr(C)]
+struct AlignedByte<const N: usize>(Align<N>, u8)
+where
+    Align<N>: Alignment;
+
+impl<const N: usize> AlignedBytes<N>
+where
+    Align<N>: Alignment,
+{
+    /// Create a new `AlignedBytes` instance from a slice
+    pub fn new(data: &[u8]) -> Box<AlignedBytes<N>> {
+        if data.is_empty() {
+            // SAFETY: The pointer isn't null and is aligned because it was returned from
+            // `NonNull::dangling`. The length is zero, so no other requirements apply.
+            unsafe {
+                Self::from_byte_ptr(
+                    ptr::NonNull::<AlignedByte<N>>::dangling()
+                        .as_ptr()
+                        .cast::<u8>(),
+                    0,
+                )
+            }
+        } else {
+            if data.len().checked_next_multiple_of(N).unwrap_or(usize::MAX) > isize::MAX as usize {
+                panic!("unable to allocate {} bytes (overflows isize)", data.len());
+            }
+
+            // SAFETY: The alignment `N` is not zero and is a power of two. `data.len()`'s next
+            // multiple of N does not overflow an `isize`.
+            let layout = unsafe { alloc::Layout::from_size_align_unchecked(data.len(), N) };
+
+            // SAFETY: `layout`'s size is not zero.
+            let ptr = unsafe { alloc::alloc(layout) };
+
+            if ptr.is_null() {
+                alloc::handle_alloc_error(layout)
+            } else {
+                // SAFETY: `data.as_ptr()` is valid for reads because it comes from a slice. `ptr` is
+                // valid for writes because it was returned from `alloc::alloc` and is not null. They
+                // can't overlap because `data` has a lifetime longer than this function and `ptr` was
+                // just allocated in this function.
+                unsafe {
+                    ptr::copy_nonoverlapping(data.as_ptr(), ptr, data.len());
+                }
+
+                // SAFETY: `ptr` is non-null, and is aligned because it was returned from `alloc::alloc`.
+                // The data pointed to is valid for reads and writes because it was initialized by
+                // `ptr::copy_nonoverlapping`. `ptr` is currently allocated by the global allocator.
+                unsafe { Self::from_byte_ptr(ptr, data.len()) }
+            }
+        }
+    }
+
+    /// # Safety
+    ///
+    /// `ptr` must be non-null, aligned to N bytes, and valid for reads and writes for `len` bytes.
+    /// The data pointed to must be initialized. If `len` is non-zero, `ptr` must be currently
+    /// allocated by the global allocator and valid to deallocate.
+    unsafe fn from_byte_ptr(ptr: *mut u8, len: usize) -> Box<AlignedBytes<N>> {
+        let slice_ptr = ptr::slice_from_raw_parts_mut(ptr, len);
+
+        // SAFETY: The invariants of `Box::from_raw` are enforced by this function's safety
+        // contract.
+        unsafe { Box::from_raw(slice_ptr as *mut AlignedBytes<N>) }
+    }
+}
+
+impl<const N: usize> Deref for AlignedBytes<N>
+where
+    Align<N>: Alignment,
+{
+    type Target = [u8];
+
+    fn deref(&self) -> &Self::Target {
+        &self.1
+    }
+}

src/backends/avx2.rs

@@ -0,0 +1,66 @@
+//! AVX2 pattern scanning backend
+
+use crate::pattern::Pattern;
+use crate::ScanResult;
+use std::arch::x86_64::{
+    _mm256_blendv_epi8, _mm256_cmpeq_epi8, _mm256_load_si256, _mm256_loadu_si256,
+    _mm256_movemask_epi8, _mm256_set1_epi8,
+};
+use std::ptr;
+
+/// Find the first occurrence of a pattern in the binary
+/// using AVX2 instructions
+///
+/// # Safety
+///
+/// * `binary` - is a valid pointer
+///
+/// * `binary_size` - corresponds to a valid size of `binary`
+///
+/// * Currently running CPU supports AVX2
+#[target_feature(enable = "avx2")]
+pub unsafe fn find(pattern_data: &Pattern, binary: *const u8, binary_size: usize) -> ScanResult {
+    const UNIT_SIZE: usize = 32;
+
+    let mut processed_size = 0;
+
+    // SAFETY: this function is only called if the CPU supports AVX2
+    unsafe {
+        let mut pattern = _mm256_load_si256(pattern_data.data.as_ptr() as *const _);
+        let mut mask = _mm256_load_si256(pattern_data.mask.as_ptr() as *const _);
+        let all_zeros = _mm256_set1_epi8(0x00);
+
+        let mut chunk = 0;
+        while chunk < binary_size {
+            let chunk_data = _mm256_loadu_si256(binary.add(chunk) as *const _);
+
+            let blend = _mm256_blendv_epi8(all_zeros, chunk_data, mask);
+            let eq = _mm256_cmpeq_epi8(pattern, blend);
+
+            if _mm256_movemask_epi8(eq) as u32 == 0xffffffff {
+                processed_size += UNIT_SIZE;
+
+                if processed_size < pattern_data.unpadded_size {
+                    chunk += UNIT_SIZE - 1;
+
+                    pattern = _mm256_load_si256(
+                        pattern_data.data.as_ptr().add(processed_size) as *const _
+                    );
+                    mask = _mm256_load_si256(
+                        pattern_data.mask.as_ptr().add(processed_size) as *const _
+                    );
+                } else {
+                    let addr = binary.add(chunk).sub(processed_size).add(UNIT_SIZE);
+                    return ScanResult { addr };
+                }
+            } else {
+                pattern = _mm256_load_si256(pattern_data.data.as_ptr() as *const _);
+                mask = _mm256_load_si256(pattern_data.mask.as_ptr() as *const _);
+                processed_size = 0;
+            }
+            chunk += 1;
+        }
+    }
+
+    ScanResult { addr: ptr::null() }
+}

src/backends/mod.rs

@@ -0,0 +1,44 @@
+//! Pattern scanning backends
+
+use crate::pattern::Pattern;
+use crate::{ScanMode, ScanResult};
+
+#[cfg(target_arch = "x86_64")]
+mod avx2;
+mod scalar;
+#[cfg(target_arch = "x86_64")]
+mod sse42;
+
+/// Find the first occurrence of a pattern in the binary
+///
+/// # Safety
+///
+/// * `binary` - is a valid pointer
+/// * `binary_size` - corresponds to a valid size of `binary`
+pub unsafe fn find(
+    pattern: &Pattern,
+    preferred_scan_mode: Option<ScanMode>,
+    binary: *const u8,
+    binary_size: usize,
+) -> ScanResult {
+    #[cfg(target_arch = "x86_64")]
+    {
+        let avx2 = is_x86_feature_detected!("avx2");
+        let sse42 = is_x86_feature_detected!("sse4.2");
+
+        match (preferred_scan_mode, avx2, sse42) {
+            (Some(ScanMode::Avx2) | None, true, _) => {
+                // SAFETY: safe to call as long as the safety conditions were met for this function
+                return unsafe { avx2::find(pattern, binary, binary_size) };
+            }
+            (Some(ScanMode::Sse42), _, true) | (None, false, true) => {
+                // SAFETY: safe to call as long as the safety conditions were met for this function
+                return unsafe { sse42::find(pattern, binary, binary_size) };
+            }
+            _ => {}
+        }
+    }
+
+    // SAFETY: safe to call as long as the safety conditions were met for this function
+    unsafe { scalar::find(pattern, binary, binary_size) }
+}