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](https://github.com/mandiant/flare-floss/releases/latest).
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.
 
:warning: **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.

:warning: 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](https://git-lfs.com/).
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](https://github.com/mandiant/flare-floss) and [test data](https://github.com/mandiant/flare-floss-testfiles).
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](https://github.com/psf/black) code formatter
  - [isort](https://pypi.org/project/isort/) code formatter
  - [mypy](https://mypy-lang.org/) type checking

We use [pre-commit](https://pre-commit.com/) 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`