avred: mapping exactly which bytes an antivirus flags

What the tool actually does, and who it is for

avred stands for AntiVirus REDucer, for AntiVirus REDteaming, and its job is to find out which parts of a file an antivirus is reacting to.

The project documentation describes it as being used to identify which parts of a file are identified by an antivirus, and it tries to show as much possible information and context about each match. That context is listed: section names of matches, verification of matches, and augmentation of matches as disassembled code or data references.

The stated purpose is to make it easier for red teamers to obfuscate their tools against static analysis, and all antivirus are supported, with AMSI used to reach them.

That framing is worth sitting with, because it says plainly what the tool is for. It reduces the effort of keeping a payload under the radar of endpoint protection, which is the same activity as any other evasion work. The same machinery also does the opposite job for a defender, because a signature that is a short byte sequence is a signature you can write a rule for, and a tool that shows you the minimal byte range that still triggers a detection is a tool for extracting those rules. The project is explicit that it is aimed at red teamers, and it is presented alongside a link to conference slides on cracking antivirus defences.

The background section explains the premise. Most antivirus engines rely on strings or other byte sequences to recognize malware, and this project helps to automatically recover these signatures, the matches.

The comparison table against ThreatCheck is a fair summary of the differences in scope. Compared to ThreatCheck, avred shows all matches rather than just one, verifies the matches to make sure they work, shows more information about each match, shows the relevance of a match so you can target the weakest one, and supports all antivirus.

The project is GPL-3.0 licensed, the primary language is Python, the default branch is main, and the last push to the repository was on 2026-06-27. There are no GitHub releases, and the project has its own site at avred.r00ted.ch.

Where the analysis comes from: file structure knowledge, not just bytes

The documented difference to similar projects is a list of three capabilities, and they are what separate avred from a scanner that reports offsets.

The first is knowledge of internal file structures. The tool can extract vbaProject.bin and modify it, it knows about PE sections and scans each one individually, and it knows about.NET streams. The second is that it supports any antivirus, thanks to an AMSI server reached over HTTP. The third is that it shows detailed information about each match, disassembly included, and verifies the matches.

Scanning each PE section individually is the part that makes the results actionable. A single offset in a 90 KB executable tells you very little, and an offset that is then labelled with the section it falls in tells you whether the detection is in the code, in the import table, in a resource or in an overlay. The example output in the documentation shows exactly that shape, with the match reported as id 0, offset 12991, length 195, and the section named as.text, followed by a hexdump of the matched bytes and the disassembly around them.

The supported file types are listed separately, and the disassembly tool differs per type: PE executables use r2 disassembly, PE.NET files use dncil disassembly, and Word files use pcodedmp disassembly. That is three different ways of understanding a container, and the choice of tool for each is a reasonable one: radare2 for native code, dncil for.NET IL, and pcodedmp for the VBA inside an Office document.

The verification step is what turns a list of offsets into a set of signatures. A match that the antivirus reports is a candidate, and a candidate is only a usable signature if it still triggers after the rest of the file is changed, and the project reports that verification per match.

The project also credits its lineage. It is similar to DefenderCheck, ThreatCheck and AMSITrigger, and it is based on avdebugger.

Setting it up, and the Windows host you cannot skip

The installation is a Python dependency install, plus two external tools, and the setup section makes one requirement explicit.

The Python dependencies come from the requirements file:

pip3 install --upgrade -r requirements.txt

and the project states a requirement of Python 3.8. If you hit the error ImportError: failed to find libmagic. Check your installation, the documented fix is:

pip3 install python-magic-bin==0.4.14

The radare2 requirement is separate, either built from the instructions on the radare2 repository or taken as a binary from its releases and added to the PATH, and the project adds a note to make sure dnfile is at 0.14.1 or newer. The requirements list also pins yara-python at 4.2.3 and dnfile at 0.14.1 exactly, and the rest of the set gives a sense of the shape of the tool: pefile, olefile and oletools for the containers, r2pipe and dncil for the disassembly, python-magic for file type detection, flask and waitress and flask-login for the web interface, hexdump and ansi2html for the reports, and intervaltree, psutil, brotli, bitstring and tabulate as supporting libraries.

The setup is where the requirement that shapes the whole workflow appears. First, we need a windows instance with an antivirus, and the project uses avred-server as the interface to that antivirus on a Windows host. The instructions are to install and configure avred-server on a Windows VM at 1.1.1.1:9001 and to follow the install instructions in the avred-server repository.

Once that is working, verified with a curl request to the test endpoint, avred is configured by pointing at the server in config.yaml, and a file is scanned with the server flag:

./avred.py --file test.ps1 --server amsi

The example output in the documentation shows the whole flow, including the case where the file is not detected at all, which is reported as an error line saying the file is not detected by amsi and a result of zero matches, and the run still writes an outcome file.

So the architecture is a Linux or macOS analysis machine talking over HTTP to a Windows machine with the antivirus, and the detection engine is a real one rather than a reimplementation of its signatures.

Running it, the file layout, and the container build

There are two ways to run the tool, and the file layout is unusually explicit about its own design.

As a web server:

python3 avredweb.py --listenip 127.0.0.1 --listenport 8080

and from the command line:

python3 avred.py --server amsi --file app/upload/evil.exe

The web server needs authentication if it is going to be shared, and the documentation says that if you do not want every user to see every uploaded file, you set a password in config.yaml under the key password, and use the username admin.

The file and directory structure section is a short paragraph with a philosophy in it. The author is team NO-DB, only files. The nomenclature is a set of suffixes next to the sample: file.exe is the file you want to scan, file.exe.log is all log output of the scanning with the logtofile option, file.exe.outcome is the pickled Outcome data structure with all further information, and file.exe.pdb is present if you have debug symbols. For the web application, files are uploaded to app/uploads/.

That is a deliberate design choice, and it has a practical benefit for a tool that handles hostile files. There is no database to compromise, because the state is a file next to the sample, aside from the optional web login. It also means the results are as durable as the filesystem and as easy to move around as a directory.

The container build is the other deployment route, and the Dockerfile is minimal: an Ubuntu 22.04 base, an apt install of libmagic1, git and python3-pip, a clone of the repository into /opt/avred, a pip install of the requirements, and the command to start the web application. The Makefile has four targets, web to run the web interface, docker-build to build the image with podman, and docker-start and docker-start-mount to run it, with the second mounting the upload directory from the host so uploads survive the container.

There is one operational wart worth knowing about, and the documentation is straightforward about it. Data is stored in pickled.outcome files, and when the model changes, weird things gonna happen. The documented recovery is to remove the outcome and log files and rescan, and with hashcache enabled that should be quick.

Where avred is the wrong tool

The first limit is the hard dependency on a Windows host with an antivirus and the avred-server bridge. That is a two-machine setup, and it means the tool is not something you run on a laptop to check a file. It is an instrument for a lab where a Windows endpoint is available, and for anyone without one, the tool cannot do its main job at all.

The second is that it is a signature-focused tool, not an analysis platform. It answers which byte ranges a detection covers and shows them in context, and it does not do the other things a malware analyst expects, such as unpacking, behavioural analysis, configuration extraction or a timeline. For that work, the tools it lists as similar, DefenderCheck and ThreatCheck, occupy the same niche, and the wider analysis world is a different set of tools entirely.

The third is the fragility of the pickled output format, and the project says so. The results are Python pickles, so a change to the model invalidates them, and the recovery is to delete and rescan. Pickle is also a format with a well-known hazard: a file that claims to be an outcome is executable content when unpickled, and the files are produced by running a tool over hostile input. A research tool for red teams is not the place to introduce that risk, and a safer serialisation would have been an easy improvement.

The fourth is the report format. The project has a companion site for the results, and the underlying data is a mix of pickles, logs and HTML fragments, which is convenient for the tool and awkward for anything that wants to index results across a campaign.

And the fifth is the purpose. The stated goal is to make it easier for red teamers to obfuscate their tools against static analysis, and while the same information is exactly what a defender needs to write a detection rule, the tool as distributed is optimised for the first job. A defender who wants signature extraction can use it, but they are working against the grain of the documentation, and they should be clear that they are using a red team tool rather than a detection engineering one.

Editorial conclusion

avred is worth running if you need to understand precisely why a payload is detected rather than just that it is, because it reports every match with its offset and section rather than a single verdict, because it verifies that a match still fires after the file is modified, which is what makes a signature recoverable rather than merely visible, and because it parses the internal structure of PE, .NET and Office files instead of treating the sample as an opaque byte stream. It is the wrong tool if you have no Windows host to scan with, and it is the wrong tool if you want a full malware analysis report. Before you set it up, check three things: that you have the AMSI server side, because the scanning is done by a real antivirus on a Windows machine reached over HTTP, so a Linux workstation alone cannot run the tool; that you understand the data format, because the results are stored in pickled .outcome files and a change to the model invalidates them, so the documented recovery is to delete the outcome and log files and rescan; and that you note the platform requirement, since the project states Python 3.8 and the install instructions call out radare2 for the PE disassembly, dnfile at 0.14.1 or newer for the .NET path and python-magic-bin for the libmagic error.

Frequently asked questions

Official sources

1. dobin/avred on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README