ASN1spect

ASN1spect is a binary analysis tool that identifies security vulnerabilities in code generated by the asn1c ASN.1 compiler. It extracts ASN.1 type descriptors directly from compiled binaries using symbolic execution and performs differential analysis to detect constraint enforcement issues, type mismatches, and other ASN.1-specific defects.

Features

• Binary-level analysis -- analyzes compiled asn1c output without requiring source code, using angr for symbolic execution
• Differential analysis -- compares two compiled binaries to detect constraint mismatches, missing members, and enumeration divergence
• Constraint checking -- identifies non-enforced encoding constraints (value ranges, size limits)
• Pluggable analysis framework -- architecture for adding new analysis modules
• srsRAN support -- dedicated analysis for srsRAN ASN.1 implementations
• IOS analysis -- extracts Protocol Information Element definitions (criticality, presence, identifiers)
• Large-scale study tooling -- automated discovery, cloning, and compilation of ASN.1 projects from GitHub

Requirements

• Python >= 3.12
• A working installation of asn1c (for compiling ASN.1 specs into binaries)

Installation

cd python/
pip install ./

This installs two CLI commands: ASN1spect and GitHub_Study.

Usage

ASN1spect

Perform differential analysis between two asn1c-compiled binaries:

ASN1spect -b <binary> -c <compare-binary>

Options:

Flag	Description
-b, --binary	Binary file to analyze (required)
-c, --compare-binary	Binary to compare against
-srs, --srsran	Path to srsRAN libs1ap_asn1.a library file
-srs-header, --srsran-header	Path to srsRAN s1ap_no_preprocessor.h header
-v, --verbose	Enable verbose output
--asn1-specs-path	Directory for ASN.1 specs (default: /data/asn1_specs)
--asn1-repo-csv	CSV mapping repositories to ASN.1 specifications
-t, --timelimit	Analysis timeout in seconds (default: 86400)

GitHub Study

Run the large-scale analysis pipeline to discover, clone, compile, and analyze GitHub repositories that use asn1c:

GitHub_Study -b <binary-dir> --compile --github-token <token> --clone-dir <dir>

Options:

Flag	Description
-b, --binary	Directory containing binary files (required)
-v, --verbose	Enable verbose output
--compile	Compile cloned repositories before analysis
--github-token	GitHub API token for cloning
--clone-dir	Directory to clone repositories into
--asn1-specs-path	Directory for ASN.1 specs
--asn1-repo-csv	CSV mapping repositories to ASN.1 specifications

Project Structure

python/
  ASN1spect/              # Core analysis package
    Analysis/             # Pluggable analysis modules
    ComparisonStrategies/ # Differential comparison logic
    FieldMatchers/        # Field matching for cross-binary comparison
    asn1c/                # asn1c type/constraint/member parsing
    srsRAN/               # srsRAN-specific analysis
    data/                 # Embedded type definitions, skeletons, and binaries
  GitHub_Study/           # Large-scale GitHub analysis pipeline
    data/                 # Cached repository data and analysis results
cpp/                      # C++ stub for linking asn1c output into binaries
scripts/                  # Shell scripts for compilation and spec extraction

How It Works

1. Binary loading -- loads the compiled binary with angr and extracts DWARF debug information
2. Symbol discovery -- finds all asn_DEF_* symbols (asn1c type descriptors)
3. Type extraction -- parses asn_TYPE_descriptor_t structures, handling multiple asn1c versions
4. Analysis execution -- runs all registered analysis modules against extracted types
5. Differential comparison -- matches corresponding types across two binaries and compares constraints
6. Result caching -- persists results via a checkpoint system for incremental analysis

Data

The dataset from our study is available in python/GitHub_Study/data/repository_data.csv, containing the GitHub repositories analyzed along with metadata such as fork status, activity status, and last update dates.

License

Apache License 2.0