Skip to content

The RF and reverse engineering framework for everyone. Follow and ★ to show your support!

License

Notifications You must be signed in to change notification settings

ainfosec/FISSURE

Repository files navigation

FISSURE - The RF Framework

Frequency Independent SDR-based Signal Understanding and Reverse Engineering

FISSURE is an open-source RF and reverse engineering framework designed for all skill levels with hooks for signal detection and classification, protocol discovery, attack execution, IQ manipulation, vulnerability analysis, automation, and AI/ML. The framework was built to promote the rapid integration of software modules, radios, protocols, signal data, scripts, flow graphs, reference material, and third-party tools. FISSURE is a workflow enabler that keeps software in one location and allows teams to effortlessly get up to speed while sharing the same proven baseline configuration for specific Linux distributions.

The framework and tools included with FISSURE are designed to detect the presence of RF energy, understand the characteristics of a signal, collect and analyze samples, develop transmit and/or injection techniques, and craft custom payloads or messages. FISSURE contains a growing library of protocol and signal information to assist in identification, packet crafting, and fuzzing. Online archive capabilities exist to download signal files and build playlists to simulate traffic and test systems.

The friendly Python codebase and user interface allows beginners to quickly learn about popular tools and techniques involving RF and reverse engineering. Educators in cybersecurity and engineering can take advantage of the built-in material or utilize the framework to demonstrate their own real-world applications. Developers and researchers can use FISSURE for their daily tasks or to expose their cutting-edge solutions to a wider audience. As awareness and usage of FISSURE grows in the community, so will the extent of its capabilities and the breadth of the technology it encompasses.

Documentation

User Manual Installation Hardware Components Operation Development Credits

Capabilities

Signal Detector
IQ Manipulation
Signal Lookup
Pattern Recognition
Attacks
Fuzzing
Signal Playlists
Image Gallery
Packet Crafting
Scapy Integration
CRC Calculator
Logging
Dataset Builder
Online Archive
Third-Party Tools
Dark and Custom Themes

Videos

Install
Target Signal Identification
Protocol Discovery
Packet Crafter
IQ Data
Archive
Attack
Library
GRCon22

Hardware

The following is a list of "supported" hardware with varying levels of integration:

  • USRP: X3xx, B2xx, B20xmini, USRP2, N2xx, X410
  • HackRF
  • RTL2832U
  • 802.11 Adapters
  • LimeSDR
  • bladeRF, bladeRF 2.0 micro
  • Open Sniffer
  • PlutoSDR

Getting Started

Supported

There are three branches within FISSURE to make file navigation easier and reduce code redundancy. Each branch codebase is dependent on the major version of Python and GNU Radio.

  • Python2_maint-3.7 branch: Python2, PyQt4, GNU Radio 3.7
  • Python3_maint-3.8 branch: Python3, PyQt5, GNU Radio 3.8
  • Python3_maint-3.10 branch: Python3, PyQt5, GNU Radio 3.10.
Operating System FISSURE Branch
Ubuntu 18.04 (x64) Python2_maint-3.7
Ubuntu 18.04.5 (x64) Python2_maint-3.7
Ubuntu 18.04.6 (x64) Python2_maint-3.7
Ubuntu 20.04.1 (x64) Python3_maint-3.8
Ubuntu 20.04.4 (x64) Python3_maint-3.8
Ubuntu 20.04.5 (x64) Python3_maint-3.8
Ubuntu 20.04.6 (x64) Python3_maint-3.8
KDE neon 5.25 (x64) Python3_maint-3.8
Ubuntu 22.04.1 (x64) Python3_maint-3.10
Ubuntu 22.04.2 (x64) Python3_maint-3.10
Ubuntu 22.04.3 (x64) Python3_maint-3.10
DragonOS FocalX (x86_64) Python3_maint-3.10

In-Progress (beta)

These operating systems are still in beta status. They are under development and several features are known to be missing. Items in the installer might conflict with existing programs or fail to install until the status is removed.

Operating System FISSURE Branch
DragonOS Focal (x86_64) Python3_maint-3.8
Parrot OS 5.2 (amd64) Python3_maint-3.8
Kali 23.1 (x64) Python3_maint-3.10
BackBox Linux 8 (amd64) Python3_maint-3.10
Raspberry Pi OS (bookworm) Python3_maint-3.10

Note: Certain software tools do not work for every OS. Refer to Known Conflicts and Third-Party Software

Installation

git clone https://github.com/ainfosec/FISSURE.git
cd FISSURE
git checkout <Python2_maint-3.7> or <Python3_maint-3.8> or <Python3_maint-3.10>
git submodule update --init
./install

This will install PyQt software dependencies required to launch the installation GUIs if they are not found. The git submodule command will download all missing GNU Radio out-of-tree modules from their repositories.

Next, select the option that best matches your operating system (should be detected automatically if your OS matches an option).

Python2_maint-3.7 Python3_maint-3.8 Python3_maint-3.10
install1b install1a install1c

It is recommended to install FISSURE on a clean operating system to avoid conflicts with existing software. The items listed under the "Minimum Install" category are what is required to launch the FISSURE Dashboard without errors. Software programs outside the minimum install are optional and can be installed as needed. Select all the recommended checkboxes (Default button) to avoid errors while operating the various tools within FISSURE. Items unchecked by default may not install properly or could possibly conflict with existing programs (please suggest fixes!). There will be multiple prompts throughout the installation, mostly asking for elevated permissions and user names. This information is primarily for installing third-party tools, refer to installation instructions provided by the maintainer for details.

If an item contains a "Verify" section at the end, the installer will run the command that follows and highlight the checkbox item green or red depending on if any errors are produced by the command. Checked items without a "Verify" section will remain black following the installation.

To avoid installation and permission errors, download FISSURE to a user owned directory such as Home. Run the install script and the fissure command without using sudo. Many of the third-party tools will be downloaded to and installed from the ~/Installed_by_FISSURE directory.

The FISSURE installer is helpful for staging computers or installing select software programs of interest. The code can be quickly modified to allow for custom software installs. The size estimates for the programs are before and after readings from a full install. The sizes for each program are not exact as some dependencies are installed in previously checked items. The sizes may also change over time as programs get updated.

Usage

Open a terminal and enter:

fissure

The intended method for launching FISSURE is through the terminal without sudo. The terminal provides important status and feedback for some operations. Refer to the FISSURE documentation for more details.

Lessons

FISSURE comes with several helpful guides to become familiar with different technologies and techniques. Many include steps for using various tools that are integrated into FISSURE. We aim to improve the quality and add new content over time.

Roadmap

Phase I

  • Provide links to videos in the README and AIS website
  • Create new FISSURE logo
  • Update documentation to instruct users how to work within the framework
  • Provide base support for hardware already on the market
  • Identify the most desirable third-party tools within the community
  • Identify the most desirable operating systems within the community
  • Release a signal conditioner that allows users to select and add techniques for isolating and conditioning signals from large streams of IQ data
  • Release a feature extractor that allows users to select and add techniques for extracting features from isolated signals for use in protocol and emitter classification
  • Release a signal classifier that allows users to select and add AI/ML techniques. In addition, a decision tree with adjustable features and weights.
  • Implement recursive demodulation mechanisms for producing a bitstream from unknown signals
  • Increase the online signal archive, support download of selectable collections
  • Support the addition of both closed source and user-developed plugins
  • Improve the look for different resolutions and window sizes, dark mode
  • Group third-party programs in the installer by type
  • Resolve DragonOS conflicts

Phase II

  • Transition the main FISSURE components to a generic sensor node deployment scheme
  • Increase automation and information exchange between components
  • Transition the FISSURE library into a database
  • Support alternative FISSURE packaging options
  • Add automatic modulation classification (AMC) techniques to the feature extractor
  • Support user selection of binary data and pattern analysis techniques
  • Improve custom Wireshark dissectors to be protocol-based and not message-based
  • Produce confidence levels against bit sequences for protocols and messages already in the library
  • Insert vulnerability analysis and automation to attacks
  • Improve the mechanism for fuzzing
  • Improve measurement, analysis, and visualization in IQ Data tab: radar data, frequency deviation, SigMF annotations
  • Create archive playlists to simulate environments
  • Develop formal classes around FISSURE (RF Attacks, Wi-Fi, GNU Radio, PyQt, etc.)
  • Expand on other untouched areas for RF and cyber (tracking, direction finding, war driving, etc.)

Phase III

  • Improve operational performance
  • Expand to other platforms
  • Insert customization for different RF environments and applications
  • Offer professional training

Concurrent

  • Clean up code, remove bugs
  • Add new help material
  • Improve status messages, system feedback, and visualization for the user
  • Integrate new hardware types as they are released
  • Expand RF protocols in list and library
  • Expand signal parameters in library
  • Expand third-party analysis tools and reference material
  • Expand support for specific operating systems
  • Produce and modify lesson material
  • Test and distribute attacks across existing hardware types (where applicable)
  • Improve installer: clean up commands, add more checks, fix broken installations
  • Provide yearly capture-the-flag contests around FISSURE
  • Support new GNU Radio releases
  • Update the project idea list every year

FISSURE Challenge

The annual "FISSURE Challenge" capture-the-flag contest to showcase new additions to FISSURE is held in December each year. Past challenges are archived and can be solved all year round! Gain hands-on experience and view solutions at: FISSURE Challenge.

Contributing

Suggestions for improving FISSURE are strongly encouraged. Leave a comment in the Discussions page or in the Discord Server if you have any thoughts regarding the following:

  • New feature suggestions and design changes
  • Software tools with installation steps
  • New lessons or additional material for existing lessons
  • RF protocols of interest
  • More hardware and SDR types for integration
  • IQ analysis scripts in Python
  • Installation corrections and improvements

Contributions to improve FISSURE are crucial to expediting its development. Any contributions you make are greatly appreciated. If you wish to contribute through code development, please fork the repo and create a pull request:

  1. Fork the project
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a pull request

Creating Issues to bring attention to bugs is also welcomed.

Need more specific ideas? There are a lot of topics we have yet to investigate. Check out our running list of potential to-do items. Any help is appreciated. Pick an easy one and write that you contributed to FISSURE in your resume/CV.

Are you a student or looking to learn more about RF and programming or an organization looking to expose students to the world of open source? Reach out today and refer to the 2023 Project Idea List.

Collaborating

Contact Assured Information Security, Inc. (AIS) Business Development to propose and formalize any FISSURE collaboration opportunities–whether that is through dedicating time towards integrating your software, having the talented people at AIS develop solutions for your technical challenges, or integrating FISSURE into other platforms/applications.

License

GPL-3.0

For license details, see LICENSE file.

Contact

Join the Discord Server: https://discord.gg/JZDs5sgxcG

Follow on Twitter/X: @FissureRF, @AinfoSec

Chris Poore - Assured Information Security, Inc. - poorec@ainfosec.com

Business Development - Assured Information Security, Inc. - bd@ainfosec.com

Acknowledgments

Special thanks to Dr. Samuel Mantravadi and Joseph Reith for their contributions to this project.

Assured Information Security

Like working with signals, reverse engineering, or other realms in cybersecurity? Browse our current openings or join our talent community for future consideration.

If you have an interest in hacking, check out our Can You Hack It?® challenge and test your skills! Submit your score to show us what you’ve got. AIS has a national footprint with offices and remote employees across the U.S. We offer competitive pay and outstanding benefits. Join a team that is not only committed to the future of cyberspace, but to our employee’s success as well.

ais