flare-floss/doc/installation.md

FLARE Obfuscated String Solver

Installation

You can install FLOSS in a few different ways. First, if you simply want to use FLOSS to extract strings, just download the standalone binaries. However, if you want to use FLOSS as a Python library, you can install the package directly from GitHub using pip. Finally, if you'd like to contribute patches or features to FLOSS, you'll need to work with a local copy of the source code.

Method 1: Using FLOSS standalone

If you simply want to use FLOSS to extract strings, use the standalone binaries we host on GitHub: https://github.com/mandiant/flare-floss/releases. These binary executable files contain all the source code, Python interpreter, and associated resources needed to make FLOSS run. This means you can run it without any installation! Just invoke the file using your terminal shell to see the help documentation.

We use PyInstaller to create these packages.

MacOS Standalone installation

By default, on macOS Catalina or greater, Gatekeeper will block execution of the standalone binary. To resolve this, simply try to execute it once on the command-line and then go to System Settings / Privacy & Security and approve the application. Alternatively, remove the quarantine attribute (enabled by default for downloaded files) from the binary before running it:

xattr -d com.apple.quarantine ./floss

Method 2: Using FLOSS as a Python library

If you'd like to use FLOSS as part of an automated analysis system, you might want to invoke it as a Python library. We designed FLOSS to be as easy to use from a client program as from the command line.

⚠️ FLOSS requires Python >= 3.10.

Step 1: Install FLOSS module

Use pip (Python >= 3.10) to install the flare-floss module to your local Python environment. This fetches the library code to your computer, but does not keep editable source files around for you to hack on. If you'd like to edit the source files, see Method 3.

• Install FLOSS:

  $ pip install flare-floss

Step 2: Use FLOSS from a Python script

You can now import the floss module from a Python script. The supported programmatic entry points are:

• floss.main.main(argv) — run the same analysis the CLI does and return the process exit code. Pass a list of arguments (for example ["sample.exe", "--json"]) in place of sys.argv[1:].
• floss.pipeline.analyze(options) — run the full analysis pipeline and return a floss.results.ResultDocument. You must build a floss.pipeline.Options object (sample path, min_length, an Analysis config, and so on).
• floss.results.ResultDocument — load and validate an existing results JSON document (ResultDocument.parse_file(path)), or construct one in memory to render with the modules under floss.render.

Example, driving the pipeline directly:

#!/usr/bin/env python
from pathlib import Path
from floss.pipeline import Options, analyze
from floss.results import Analysis

options = Options(
    sample=Path("malware.exe"),
    min_length=4,
    analysis=Analysis(),
)
doc = analyze(options)
print(len(doc.strings.stack_strings), "stack strings")

These are the current programmatic interfaces. The CLI (floss ...) remains the stable, documented interface — the Python API can change between releases, so pin the flare-floss version if you rely on it.

⚠️ Importing floss does not itself register any convenience functions; dir(floss) is not a useful listing. Use the entry points above instead.

Method 3: Inspecting the FLOSS source code

If you'd like to review and modify the FLOSS source code, you'll need to check it out from GitHub and install it locally. By following these instructions, you'll maintain a local directory of source code that you can modify and run easily.

Step 1: Check out source code

• Clone the FLOSS git repository:

  $ git clone https://github.com/mandiant/flare-floss /local/path/to/src

Several large data files (tag databases under floss/tags/data/ and FLIRT signatures under floss/sigs/) are tracked with Git LFS. Ensure Git LFS is installed (git lfs install) and that the clone has the filters enabled, then fetch the large objects with:

`$ git lfs pull`

Without these files the tag and signature features will be silently missing or empty.

Step 2: Install the local source code

Next, use pip to install the source code in "editable" mode. This means that Python will load the FLOSS module from this local directory rather than copying it to site-packages or dist-packages. This is good, because it is easy for us to modify files and see the effects reflected immediately. But be careful not to remove this directory unless uninstalling FLOSS! If you encounter the error ERROR: Project has a 'pyproject.toml' and its build backend is missing the 'build_editable' hook., please ensure that you have upgraded to the latest versions of pip and setuptools.

• Install FLOSS:

  $ pip install -e /local/path/to/src

You'll find that the floss.exe (Windows) or floss (Linux, macOS) executables in your path now invoke the FLOSS binary from this directory.

Step 3: Install development and testing dependencies

When developing FLOSS, please use the pinned dependencies found in requirements.txt. This ensures that everyone has the exact same, reproducible environment. Please install these dependencies before install FLOSS (from source or from PyPI):

$ pip install -r requirements.txt

To install all testing and development dependencies, run:

$ pip install -e /local/path/to/src[dev]

We use a git submodule to separate code and test data. To clone everything use the --recurse-submodules option:

• $ git clone --recurse-submodules https://github.com/mandiant/flare-floss.git /local/path/to/src (HTTPS)
• $ git clone --recurse-submodules git@github.com:mandiant/flare-floss.git /local/path/to/src (SSH)

Or use the manual option:

• clone repository
  • $ git clone https://github.com/mandiant/flare-floss.git /local/path/to/src (HTTPS)
  • $ git clone git@github.com:mandiant/flare-floss.git /local/path/to/src (SSH)
• $ cd /local/path/to/src
• $ git submodule update --init tests/data

We use the following tools to ensure consistent code style and formatting:

• black code formatter
• isort code formatter
• mypy type checking

We use pre-commit so that its trivial to run the same linters & configuration locally as in CI.

Run all linters liks:

❯ pre-commit run --all-files
isort....................................................................Passed
black....................................................................Passed
mypy.....................................................................Passed

Or run a single linter like:

❯ pre-commit run --all-files isort
isort....................................................................Passed

Importantly, you can configure pre-commit to run automatically before every commit by running:

❯ pre-commit install --hook-type pre-commit
pre-commit installed at .git/hooks/pre-commit

❯ pre-commit install --hook-type pre-push
pre-commit installed at .git/hooks/pre-push

This way you can ensure that you don't commit code style or formatting offenses. You can always temporarily skip the checks by using the -n/--no-verify git option.

The linters and tests run in CI must all pass before a pull request is merged.

Step 4: Building standalone executables

Once you're happy with your contribution to FLOSS, you can package and distribute a standalone executable for your friends using PyInstaller. This combines the source code, Python interpreter, and required resources into a single file that can be run without installation.

• Install pyinstaller:

  $ pip install pyinstaller

• Build standalone executable:

  $ pyinstaller .github/pyinstaller/floss.spec

• Distribute standalone executable:

  $ cp ./dist/floss.exe /the/internet