{"id":13699203,"url":"https://github.com/fkie-cad/FACT_core","last_synced_at":"2025-05-04T16:32:46.886Z","repository":{"id":37773803,"uuid":"104088122","full_name":"fkie-cad/FACT_core","owner":"fkie-cad","description":"Firmware Analysis and Comparison Tool","archived":false,"fork":false,"pushed_at":"2024-11-12T11:03:49.000Z","size":60165,"stargazers_count":1235,"open_issues_count":140,"forks_count":224,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-11-12T11:38:39.105Z","etag":null,"topics":["firmware-analysis","firmware-tools","security","security-automation"],"latest_commit_sha":null,"homepage":"https://fkie-cad.github.io/FACT_core","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fkie-cad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-19T14:48:11.000Z","updated_at":"2024-11-10T02:14:53.000Z","dependencies_parsed_at":"2022-07-04T08:01:12.787Z","dependency_job_id":"fa51555d-6cff-44dc-a573-fd9615319ba4","html_url":"https://github.com/fkie-cad/FACT_core","commit_stats":{"total_commits":4030,"total_committers":54,"mean_commits":74.62962962962963,"dds":0.6178660049627791,"last_synced_commit":"e0dc06dfea7b31160c636eb96f1b2729fae3c8d2"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FFACT_core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FFACT_core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FFACT_core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkie-cad%2FFACT_core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fkie-cad","download_url":"https://codeload.github.com/fkie-cad/FACT_core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224398823,"owners_count":17304661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firmware-analysis","firmware-tools","security","security-automation"],"created_at":"2024-08-02T20:00:19.911Z","updated_at":"2025-05-04T16:32:46.876Z","avatar_url":"https://github.com/fkie-cad.png","language":"Python","funding_links":[],"categories":["Python","Firmware Tools, Libraries, and Frameworks","Firmware Security","📚 Table of Contents"],"sub_categories":["Static Analysis Tools","Firmware Analysis \u0026 Extraction"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"src/web_interface/static/FACT_smaller.png\" alt=\"FACT logo with magnifying glass as the C\" /\u003e\n  \u003cbr/\u003e\n  The Firmware Analysis and Comparison Tool (FACT)\n\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n  [![codecov](https://codecov.io/gh/fkie-cad/FACT_core/branch/master/graph/badge.svg)](https://codecov.io/gh/fkie-cad/FACT_core)\n  [![Codacy Badge](https://app.codacy.com/project/badge/Grade/d3910401cb58498a8c2d00be80092080)](https://www.codacy.com/gh/fkie-cad/FACT_core/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=fkie-cad/FACT_core\u0026amp;utm_campaign=Badge_Grade)\n  [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/FACT_core/community)\n  [![CI Build](https://github.com/fkie-cad/FACT_core/actions/workflows/build_ci.yml/badge.svg)](https://github.com/fkie-cad/FACT_core/actions/workflows/build_ci.yml)\n  [![Ruff](https://github.com/fkie-cad/FACT_core/actions/workflows/ruff.yml/badge.svg)](https://github.com/fkie-cad/FACT_core/actions/workflows/ruff.yml)\n  [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n\u003c/div\u003e\n\n## Contents\n\n- [Why FACT?](#why-fact)\n- [Setup](#setup)\n- [Usage](#usage)\n- [Documentation](#documentation)\n- [Contribute](#contributing)\n- [Additional plugins](#additional-plugins)\n- [Analysis Import/Export](#analysis-import--export)\n- [Presentations](#presentations)\n- [Social](#social)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n\n## Why FACT?\n\nFirmware analysis can be used to achieve several interesting goals.\nChief among those are identifying functionality, components and potential security weaknesses in black box firmware.\n\nThe Firmware Analysis and Comparison Tool (FACT) is intended to automate as much as possible of the manual firmware\nanalysis work.\nFACT combines a growing set of powerful analyses to create a unified interface that brings the user from an arbitrary\nfirmware sample to a finished analysis.\nSome of the key features of the FACT analysis, is that results are\n\n- browsable\n- searchable\n- and comparable.\n\nFurthermore, FACT offers multiple ways of navigating and visualizing analysis results and firmware contents for easy accessibility.\nThe main FACT interface is a html/js/css-based web Interface that can be hosted locally or shared through the network.\nIn addition, FACT offers a REST-like HTTP API that can be explored with an integrated SwaggerUI.\nSome key features of the web interface are:\n\n- Easy visualization of firmware by a file tree rendering of all firmware components.\n- Quick navigation of analysis results by observing summaries of results over all firmware components.\n- Highlighting of relevant analysis results as tags on top of each page.\n- Various download options for firmware and components to jump into advanced analysis.\n\nWhile FACT is maintained as a research prototype, the project is well tested, includes a baseline of documentation and\noffers a multitude of production level features.\nWe're always looking for feedback and feature requests.\n\nMore details and some screenshots can be found on our [project page](https://fkie-cad.github.io/FACT_core/).\n\n## Setup\n\n### Requirements\n\nFACT is designed as a multiprocess application, the more Cores and RAM, the better.\n\n| Minimal          | Recommended       |\n|------------------|-------------------|\n| 4 Cores          | 16 Cores          |\n| 8 GB RAM         | 64 GB RAM         |\n| 10 GB disk space | 10* GB disk space |\n\n\u003e [!NOTE]\n\u003e About 10 GB required to set up FACT code, container, and binaries.\n\u003e Additional space is necessary for storage of unpacked files and analysis results.\n\u003e This can be on a separate partition or drive.\n\n### Local Installation\n\nIt's principally possible to install FACT on any Linux distribution, but the installer is limited to\n\n- Debian 11/12 (stable)\n- Ubuntu 20.04/22.04/24.04 (stable)\n- Linux Mint 20/21/22 (stable)\n- Kali (experimental)\n\nFACT requires Python 3.9–3.12 (should be the default in all distributions except Ubuntu 20.04 where you can install\na newer version using `apt`)\n\nThe setup process is mostly automated and wrapped in a single script.\nSome features can be selected specifically though.\nFor a detailed guide on how to install FACT see\n[INSTALL.md](https://github.com/fkie-cad/FACT_core/blob/master/INSTALL.md).\n\n\u003e [!IMPORTANT]\n\u003e Note that while making extensive use of containers, FACT still contains many dependencies\n\u003e (and there is no _uninstall_ provided).\n\u003e If you want to keep your system clean, you can try one of the setup options provided in the following.\n\n### Vagrant\n\nWe provide monthly and ready-to-use vagrant boxes of our master branch.\n[Vagrant](https://www.vagrantup.com/) is an easy and convenient way to get started with FACT without having to install\nit on your machine.\nJust setup vagrant and import our provided box into VirtualBox.\nOur boxes can be found [here](https://app.vagrantup.com/fact-cad/boxes/FACT-master)!\n\nCheck out on how to get started with FACT and vagrant in\nour [tutorial](https://github.com/fkie-cad/FACT_core/blob/master/INSTALL.vagrant.md).\n\n### Docker\n\nThere is also a dockerized version, but it is currently unmaintained.\n(see the [FACT_docker](https://github.com/fkie-cad/FACT_docker) repo for more information).\n\n## Usage\n\nYou can start FACT by executing the `start_fact.py` script.\nThe script detects all installed components automatically.\n\n```sh\nsrc/start_fact.py\n```\n\nAfterward, FACT can be accessed on \u003chttp://localhost:5000\u003e (default) or \u003chttps://localhost\u003e (if FACT is installed with\nnginx).\n\nYou can shut down the system by pressing \u003ckbd\u003eCtrl + c\u003c/kbd\u003e or by sending a SIGTERM to the `start_fact.py` script.\n\n\u003e [!CAUTION]\n\u003e FACT is not intended to be used as a public internet service.\n\u003e The web interface is not a hardened application.\n\u003e We try to keep security issues limited by applying SecDevOps but FACT may still offer vulnerabilities.\n\u003e Make sure to reset all passwords in the fact configuration if planning to host FACT on not-fully trusted networks.\n\n## Documentation\n\n\u003e [!TIP]\n\u003e More documentation on how to use FACT can be found on\nour [wiki pages](https://github.com/fkie-cad/FACT_core/wiki/).\n\nOur Sphinx documentation can be found [here](https://fkie-cad.github.io/FACT_core/).\n\nInformation on what FACT is and how it works can also be found in the slides in the\n[`docs` folder](https://github.com/fkie-cad/FACT_core/tree/master/docs).\n\n### REST API\n\nFACT provides a REST API. More information can be found [here](https://github.com/fkie-cad/FACT_core/wiki/Rest-API).\n\n### User Management\n\nFACT provides an optional basic authentication, role, and user management.\nMore information can be found [here](https://github.com/fkie-cad/FACT_core/wiki/Authentication).\n\n## Contributing\n\nThe easiest way to contribute is writing your own plugin.\nOur Developer Manual can be found [here](https://github.com/fkie-cad/FACT_core/wiki/).\n\n## Additional plugins\n\nCurrently available additional plugins:\n\n- [Codescanner](https://github.com/fkie-cad/Codescanner_FACT_plugin) (:warning: different license)\n    - Classification of segments (e.g. ascii / code / high entropy) in arbitrary binaries\n    - Classification of cpu architecture in code segments\n\n## Analysis Import / Export\n\nThe script `src/firmware_import_export.py` can be used to export unpacked files and analysis results and import them\ninto another FACT instance.\nThe data is stored as a ZIP archive, and this is also the format the script expects during import.\nTo export files and analysis data of analyzed firmware images, run\n\n```shell\npython3 firmware_import_export.py export FW_UID [FW_UID_2 ...] [-o OUTPUT_DIR]\n```\n\n\u003e [!NOTE]\n\u003e The exported archives can take up significant disk space.\n\u003e There is no fixed relation, but it can surpass the size of the original firmware by a factor of 2 - 10.\n\nAfter this, you can import the exported files with\n\n```shell\npython3 firmware_import_export.py import FW.zip [FW_2.zip ...]\n```\n\n## Presentations\n\n### BlackHat Arsenal\n\nWe've been happy to show FACT in a number of BlackHat Arsenal sessions.\n\n- [![Black Hat Arsenal](https://github.com/toolswatch/badges/blob/master/arsenal/asia/2018.svg)](http://www.toolswatch.org/2018/01/black-hat-arsenal-asia-2018-great-lineup/)\n- [![Black Hat Arsenal](https://github.com/toolswatch/badges/blob/master/arsenal/europe/2018.svg)](http://www.toolswatch.org/2018/09/black-hat-arsenal-europe-2018-lineup-announced/)\n- [![Black Hat Arsenal](https://github.com/toolswatch/badges/blob/master/arsenal/usa/2019.svg)](http://www.toolswatch.org/2019/05/amazing-black-hat-arsenal-usa-2019-lineup-announced/)\n- [![Black Hat Arsenal](https://github.com/toolswatch/badges/blob/master/arsenal/europe/2019.svg)](https://www.blackhat.com/eu-19/arsenal/schedule/#fact--firmware-analysis-and-comparison-tool-18179)\n- [![Black Hat Arsenal](https://github.com/toolswatch/badges/blob/master/arsenal/usa/2022.svg)](https://www.blackhat.com/us-22/arsenal/schedule/#fact--26776)\n\n### Other\n\n- [Hardwear.io 2017](https://hardwear.io/the-hague-2017/speakers/johannes-vom-dorp.php) / [Slides](https://hardwear.io/document/hio.pdf)\n- [Pass the salt 2019](https://2019.pass-the-salt.org/talks/71.html) /\n  [Slides](https://2019.pass-the-salt.org/files/slides/04-FACT.pdf) /\n  [Video](https://passthesalt.ubicast.tv/videos/improving-your-firmware-security-analysis-process-with-fact/)\n- [Hardwear.io 2019](https://hardwear.io/netherlands-2019/speakers/johannes-vom-dorp-and-peter-weidenbach.php)\n\n## Social\n\n- [Twitter](https://twitter.com/FAandCTool)\n- [Gitter](https://app.gitter.im/?updated=1.11.30#/room/#FACT_core_community:gitter.im)\n\n## Acknowledgments\n\nThanks to @botlabsDev, who initially provided a [Vagrantfile](https://github.com/botlabsDev/FACTbox) that is now,\nhowever, deprecated.\n\nThis project is partly financed by [German Federal Office for Information Security (BSI)](https://www.bsi.bund.de) and\nothers.\n\n## License\n\n\u003e Firmware Analysis and Comparison Tool (FACT)\n\u003e\n\u003e Copyright (C) 2015-2024 Fraunhofer FKIE\n\u003e\n\u003e This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public\n\u003e License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any\n\u003e later version.\n\u003e This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\n\u003e warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  \n\u003e See the GNU General Public License for more details.\n\u003e You should have received a copy of the GNU General Public License along with this program.  \n\u003e If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\u003e\n\u003e Some plugins may have different licenses.\n\u003e If so, a license file is provided in the plugin's folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkie-cad%2FFACT_core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffkie-cad%2FFACT_core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkie-cad%2FFACT_core/lists"}