dobin/avred

1. What this repository is

avred is a two-part system: a command-line scanning/reduction engine and a small web UI for managing uploaded samples and viewing results. Its core job is to probe an antivirus/AMSI backend, find which byte ranges trigger detection, and then enrich those ranges with file-structure context.

2. Primary execution entry points

avred.py is the main CLI workflow for scanning a single file end-to-end. avredweb.py is the web server entry point. The app/ directory contains the web application layer: templates, static assets, and Flask-style view modules for browsing files, upload/login, and per-file result pages.

3. Core scan pipeline

The scan path starts with file identification and parser selection, then feeds byte ranges into the configured scanner backend. The repo distinguishes between whole-file handling and structure-aware scanning, so PE sections, Office macro payloads, and .NET streams can be tested independently rather than only as one blob.

4. Scanner/backend boundary

The actual detection engine is external: avred talks to an AMSI server over HTTP, configured in config.yaml. This makes the antivirus boundary explicit: avred does local analysis and orchestration, while the remote Windows/AMSI service decides whether a sample or byte slice is malicious.

5. File-type plugin architecture

The plugins/ tree is the main architectural extension point. There are specialized plugins for:

- pe/ for Windows executables

- office/ for Word/macros and embedded vbaProject.bin

- dotnet/ for .NET assemblies and metadata streams

- plain/ for unstructured files/scripts

Each plugin has a file_* module for file-specific parsing, an analyzer_* module for interpreting hits, and in some cases augment_* / outflank_* modules for extra context and reduction strategies.

6. Verification and reduction workflow

After initial detection, the system does not stop at “something matched.” verifier.py, minimizer.py, reducer.py, and scanner.py work together to confirm that matches are real, narrow them down, and rank or split them into smaller actionable regions. This is what enables avred to show multiple verified matches instead of a single coarse hit.

7. Model and persistence layer

The model/ package defines the persisted outcome structures: files, code/data matches, verification state, and plugin-specific metadata. Results are stored as pickled .outcome files alongside .log files in the upload directory, which is why the README warns that model changes can invalidate older results.

8. Augmentation and disassembly context

A major differentiator is match augmentation. For PE files, disassembly/context can come from radare2; for .NET, the repo vendors dnfile/dotnetfile plus dncil-based parsing; for Office macros, it vendors pcodedmp. These tools are used to explain a match in terms of code, sections, streams, and references rather than raw offsets only.

9. Web application responsibilities

The web UI in app/ is presentation and file management, not the scanning engine. It renders uploaded files, file info, match lists, logs, verifier status, and upload tracking. Authentication is optional and appears to be simple shared-password protection configured in config.yaml.

10. Storage and operational model

The system is intentionally file-centric: uploaded samples live under app/upload/, examples under app/examples/, and all derived data stays on disk next to the sample. That keeps the architecture stateless from the web server’s perspective, but means the filesystem is the persistence boundary for outcomes, logs, and patched artifacts.

11. Tooling and offline utilities

The tools/ directory contains helper scripts for viewing pickles, patching files, and verifying outputs outside the main app flow. The tests/ tree exercises the scanners, parsers, model logic, and verifier behavior using sample PE, Office, and .NET artifacts, which reflects the repo’s modular, file-type-driven design.

12. Big-picture data flow

Input file → file-type detection → plugin-specific parsing/context extraction → HTTP scan against AMSI → match collection → verification/minimization → augmentation with disassembly/structure metadata → persisted outcome/logs → optional web UI display and offline tooling.

The key architectural boundaries are: local analysis vs remote antivirus, generic scan orchestration vs file-type plugins, and engine logic vs web presentation.