feat!: Allow providing reference programs as raw pcode (#89)

* Add reference program support for binary and raw pcode specifications

- Introduce ReferenceProgram struct representing steps and initial
  memory valuation
- Implement loading reference programs from binary files and raw pcode
  strings
- Add MemoryValuation helper for managing initial memory constraints
- Refactor specification config to support binary files or raw pcode
- Update dependency on jingle to 0.4.0 to support new features

* Update jingle dependency to version 0.4.0 with features

* clippy

* Refactor SpecificationConfig into a discriminated union

Split SpecificationConfig into BinaryFileSpecification and
RawPcodeSpecification to clearly represent the two specification
variants.

* Refactor reference program config using discriminated union

Define BinaryFileSpecification and RawPcodeSpecification models with a
discriminator field `type` for improved type safety and clarity. Add
detailed docstrings and helper repr methods.

* Transform specification JSON for Rust enum compatibility in run()

* Refactor imports and update __all__ in config init

* Improve PythonLoggerLayer to pass metadata via `extra` dictionary

Pass Rust file, line, and module path metadata separately to Python
logging to enable better integration without embedding them in the
message.

* Refactor configuration imports and update examples for raw pcode

- Rearrange imports in Python and Rust code for clarity and consistency
- Replace reference program file with raw pcode specification in
  examples
- Adjust logging levels and output formatting for better debug info
- Update bench command to handle specification variants correctly
- Simplify tracing calls and improve error/info logging messages

* Update jingle dependency to version 0.4.2 in Cargo.toml files

Remove backup Cargo.toml~ file from crackers_python directory

Author: toolCHAINZ

README.md

@@ -61,24 +61,26 @@ logging.basicConfig(level=logging.INFO)
 from z3 import BoolRef, BoolVal, simplify
 
 from crackers.config import (
-    MetaConfig,
+    BinaryFileSpecification,
+    ConstraintConfig,
+    CrackersConfig,
     LibraryConfig,
-    SleighConfig,
+    MetaConfig,
     ReferenceProgramConfig,
+    SleighConfig,
     SynthesisConfig,
-    ConstraintConfig,
-    CrackersConfig,
 )
 from crackers.config.constraint import (
-    RegisterValuation,
-    RegisterStringValuation,
-    MemoryValuation,
-    PointerRange,
     CustomStateConstraint,
     CustomTransitionConstraint,
+    MemoryValuation,
+    PointerRange,
     PointerRangeRole,
+    RegisterStringValuation,
+    RegisterValuation,
 )
 from crackers.config.log_level import LogLevel
+from crackers.config.specification import BinaryFileSpecification, RawPcodeSpecification
 from crackers.config.synthesis import SynthesisStrategy
 
 
@@ -95,14 +97,17 @@ def my_transition_constraint(block: ModeledBlock) -> BoolRef:
     return BoolVal(True)
 
 
-meta = MetaConfig(log_level=LogLevel.INFO, seed=42)
+pcode = """
+RBX = COPY 0x1337:8
+BRANCH *[ram]0xdeadbeef:8
+"""
+
+meta = MetaConfig(log_level=LogLevel.DEBUG, seed=42)
 library = LibraryConfig(
-    max_gadget_length=8, path="libz.so.1", sample_size=None, base_address=None
+    max_gadget_length=8, path="libnscgi.so", sample_size=None, base_address=None
 )
 sleigh = SleighConfig(ghidra_path="/Applications/ghidra")
-reference_program = ReferenceProgramConfig(
-    path="sample.o", max_instructions=8, base_address=library.base_address
-)
+reference_program = RawPcodeSpecification(raw_pcode=pcode)
 synthesis = SynthesisConfig(
     strategy=SynthesisStrategy.SAT,
     max_candidates_per_slot=200,
@@ -141,7 +146,7 @@ match r:
                 print(i.disassembly)
             print()
         for name, bv in a.input_summary(True):
-            print(f"{name} = {simplify(bv)}")
+            print(f"{name} = {hex(simplify(bv).as_long())}")
 
 ```
 

crackers/Cargo.toml

@@ -24,7 +24,7 @@ toml = ["dep:toml_edit"]
 z3-gh-release = ["z3/gh-release"]
 
 [dependencies]
-jingle = { version = "0.3.6", features = ["gimli"] }
+jingle = { version = "0.4.2", features = ["gimli"] }
 z3 = "0.19.0"
 serde = { version = "1.0.203", features = ["derive"] }
 thiserror = "2.0"

crackers/src/bench/mod.rs

@@ -2,10 +2,10 @@ use std::fs;
 use std::path::PathBuf;
 
 use clap::Parser;
-use tracing::level_filters::LevelFilter;
-use tracing::{Level, event};
+use tracing::{Level, error, info};
 use tracing_indicatif::IndicatifLayer;
 use tracing_subscriber::EnvFilter;
+use tracing_subscriber::filter::LevelFilter;
 use tracing_subscriber::layer::SubscriberExt;
 use tracing_subscriber::util::SubscriberInitExt;
 
@@ -18,43 +18,55 @@ pub struct BenchCommand {
     gadgets_per_slot: usize,
     spec_instructions: usize,
 }
+
 pub fn bench(config: BenchCommand) -> anyhow::Result<()> {
     let cfg_bytes = fs::read(config.crackers_config)?;
     let s = String::from_utf8(cfg_bytes)?;
     let mut p: CrackersConfig = toml_edit::de::from_str(&s)?;
     p.synthesis.max_candidates_per_slot = config.gadgets_per_slot;
-    p.specification.max_instructions = config.spec_instructions;
+    match &mut p.specification {
+        crate::config::specification::SpecificationConfig::BinaryFile(b) => {
+            b.max_instructions = config.spec_instructions;
+        }
+        _ => {}
+    }
 
+    // Resolve log level from config (expects a compatible type in `p.meta.log_level`)
     let level = Level::from(p.meta.log_level);
+
     let env_filter = EnvFilter::builder()
         .with_default_directive(LevelFilter::ERROR.into())
         .from_env()?
         .add_directive(format!("crackers={level}").parse()?);
+
     let indicatif_layer = IndicatifLayer::new();
     let writer = indicatif_layer.get_stderr_writer();
+
     tracing_subscriber::registry()
         .with(env_filter)
         .with(indicatif_layer)
         .with(tracing_subscriber::fmt::layer().with_writer(writer))
         .init();
+
     let params = p.resolve()?;
     match params.build_single() {
         Ok(mut a) => match a.decide() {
             Ok(a) => match a {
                 DecisionResult::AssignmentFound(_) => {
-                    event!(Level::INFO, "synth_success")
+                    info!("synth_success");
                 }
                 DecisionResult::Unsat(_) => {
-                    event!(Level::INFO, "synth_fail")
+                    info!("synth_fail");
                 }
             },
             Err(e) => {
-                event!(Level::ERROR, "synth_error: {}", e)
+                error!("synth_error: {}", e);
             }
         },
         Err(_) => {
-            event!(Level::ERROR, "synth_fail")
+            error!("synth_fail");
         }
     }
+
     Ok(())
 }

crackers/src/bin/crackers/main.rs

@@ -54,11 +54,16 @@ fn main() {
 fn new(path: PathBuf) -> anyhow::Result<()> {
     let config = CrackersConfig {
         meta: Default::default(),
-        specification: SpecificationConfig {
-            path: "spec.o".to_string(),
-            max_instructions: 1,
-            base_address: None,
-        },
+        specification: SpecificationConfig::RawPcode(
+            r"
+                MOV RDI, 0xdeadbeef:8
+                MOV RSI, 0x40:8
+                MOV RDX, 0x7b:8
+                MOV RAX, 0xfacefeed:8
+                BRANCH 0xdeadbeef:8
+                "
+            .to_string(),
+        ),
         library: Default::default(),
         sleigh: SleighConfig {
             ghidra_path: "/Applications/ghidra".to_string(),

crackers/src/config/error.rs

@@ -22,7 +22,7 @@ pub enum CrackersConfigError {
         "Unable to determine the architecture of the provided object file. This is a config file limitation and not a sleigh limitation."
     )]
     UnrecognizedArchitecture(String),
-    #[error("An error initializing sleigh for a file specified in the config")]
+    #[error("An error initializing sleigh for a file specified in the config: {0}")]
     Sleigh(#[from] JingleError),
 }
 

crackers/src/config/mod.rs

@@ -35,6 +35,7 @@ pub struct CrackersConfig {
 impl CrackersConfig {
     pub fn resolve(&self) -> Result<SynthesisParams, CrackersError> {
         let library = self.library.build(&self.sleigh)?;
+        let lang_id = library.language_id.clone();
         let mut b = SynthesisParamsBuilder::default();
         if let Some(c) = &self.constraint {
             b.preconditions(c.get_preconditions(&library.arch_info()).collect());
@@ -47,6 +48,7 @@ impl CrackersConfig {
                 &self.specification,
                 &self.sleigh,
                 &self.library.operation_blacklist,
+                &lang_id,
             )?);
         b.selection_strategy(self.synthesis.strategy);
         b.combine_instructions(self.synthesis.combine_instructions);

crackers/src/config/specification.rs

@@ -14,15 +14,22 @@ use crate::config::sleigh::SleighConfig;
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(feature = "pyo3", pyclass(get_all, set_all))]
-pub struct SpecificationConfig {
+pub struct BinaryFileSpecification {
     pub path: String,
     pub max_instructions: usize,
     pub base_address: Option<u64>,
 }
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[cfg_attr(feature = "pyo3", pyclass)]
+pub enum SpecificationConfig {
+    BinaryFile(BinaryFileSpecification),
+    RawPcode(String),
+}
+
 #[cfg(feature = "pyo3")]
 #[pymethods]
-impl SpecificationConfig {
+impl BinaryFileSpecification {
     #[new]
     fn new(path: String, max_instructions: usize, base_address: Option<u64>) -> Self {
         Self {
@@ -63,7 +70,7 @@ impl SpecificationConfig {
     }
 }
 
-impl SpecificationConfig {
+impl BinaryFileSpecification {
     fn load_sleigh<'a>(
         &self,
         sleigh_config: &'a SleighConfig,

crackers/src/gadget/library/mod.rs

@@ -19,6 +19,7 @@ pub mod image;
 pub struct GadgetLibrary {
     pub(crate) gadgets: Vec<Gadget>,
     arch_info: SleighArchInfo,
+    pub(crate) language_id: String,
 }
 
 impl AsRef<SleighArchInfo> for GadgetLibrary {
@@ -52,6 +53,7 @@ impl GadgetLibrary {
         let mut lib: GadgetLibrary = GadgetLibrary {
             gadgets: vec![],
             arch_info: sleigh.arch_info().clone(),
+            language_id: sleigh.get_language_id().to_string(),
         };
         event!(Level::INFO, "Loading gadgets from sleigh");
         for section in sleigh.get_sections().filter(|s| s.perms.exec) {