Metadata-Version: 2.1
Name: rugosa
Version: 1.3.0
Summary: A static malware analysis library and tool developed using the disassembler-agnostic Dragodis.
Author-email: DC3 <dc3.tsd@us.af.mil>
License: DC3 Rugosa Open Source License
        
        DC3 Rugosa software was developed by the Department of Defense Cyber Crime Center (DC3). By delegated authority pursuant to Section 801(b) of Public Law 113-66, as amended,
        DC3 grants the following license for this software:
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following condition:
        
        The above permission notice and the below warranty notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE DEVELOPERS, OR LICENSORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/dod-cyber-crime-center/rugosa
Project-URL: Repository, https://github.com/dod-cyber-crime-center/rugosa.git
Project-URL: Changelog, https://github.com/dod-cyber-crime-center/rugosa/blob/master/CHANGELOG.md
Keywords: malware,ida,idapro,ghidra,emulation,strings,regex,yara
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dragodis>=1.1.0
Requires-Dist: dynaconf
Requires-Dist: platformdirs
Requires-Dist: cmd2>=3.0.0rc1
Requires-Dist: pyreadline3; platform_system == "Windows"
Requires-Dist: tabulate
Requires-Dist: hexdump
Requires-Dist: pyhidra>=0.6.0
Requires-Dist: yara-python
Provides-Extra: testing
Requires-Dist: pytest>=3.0.0; extra == "testing"
Requires-Dist: pytest-datadir; extra == "testing"

# Rugosa

Rugosa is a static malware analysis library and tool developed using the disassembler-agnostic 
[dragodis](https://github.com/dod-cyber-crime-center/dragodis) API. It incorporates a binary emulation framework along with
utilities for regex and YARA searching, string extraction, and function discovery within disassembled code.
These features enhance capabilities for comprehensive malware analysis and metadata extraction.

Rugosa utilizes an in-house developed emulation engine entirely written in Python to achieve full control of the execution
context and offer high-level abstractions for emulated artifacts. 
It adopts a targeted approach employing branch path tracing to emulate portions of code without the need to fully
emulate preceding code or modify the binary to accommodate such control flow.

Currently, x86 and ARM processors are supported.


## Install

```
pip install rugosa
```

You will also need to setup a backend disassembler by following [Dragodis's installation instructions](https://github.com/dod-cyber-crime-center/dragodis/blob/master/docs/install.md).


## Utilities

The following utilities are included with Rugosa:
- [Emulation](./docs/CPUEmulation.md)
- [Extra Disssembly Interfaces](./rugosa/disassembly.py)
- [Regex](./docs/Regex.md)
- [Strings](./rugosa/strings.py)
- [YARA](./docs/YARA.md)


## Configuration

All options are configurable through a [settings.toml](src/rugosa/config/settings.toml) file.
This file can be modified to configure Rugosa.

Rugosa looks for a user defined configuration file at either `~/.config/rugosa/settings.toml` or `%LOCALAPPDATA%\dc3\rugosa\settings.toml`
to overwrite the default settings.

To view the current configuration run the following:
```shell
python -m rugosa.config list
```

To edit the configuration run the following to open the file in a text editor.
(This will copy the default configuration into a user directory)
```shell
python -m rugosa.config edit
```

To create a new user configuration file without editing:
```shell
python -m rugosa.config create
```

We use [Dynaconf](https://dynaconf.com) which provides conveniences like setting configuration using environment variables
prefixed with `RUGOSA_`.

For example, to change the computer name used during emulation:

```shell
export RUGOSA_MACHINE__COMPUTER_NAME=BOB_PC  # '__' to access nested field.
```


## Interactive Shell

Rugosa includes an interactive shell created with [cmd2](https://cmd2.readthedocs.io) for emulating and traversing a given binary.
For more information on how to use the tool, please see the [documentation](./docs/Shell.md).

![](docs/assets/shell.gif)


## Emulator Plugin

Rugosa includes a IDA and Ghidra plugin which provides a GUI for using the [emulation](./docs/CPUEmulation.md) utility.
For more information on how to install and use the plugin please see the [documentation](./docs/EmulatorPlugin.md).

![](docs/assets/ida_overview.png)

![](docs/assets/ghidra_overview.png)
