Merge pull request #1763 from mandiant/v6.1.0

version: v6.1.0

.devcontainer/Dockerfile

@@ -0,0 +1,21 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.233.0/containers/python-3/.devcontainer/base.Dockerfile
+
+# [Choice] Python version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.10, 3.9, 3.8, 3.7, 3.6, 3-bullseye, 3.10-bullseye, 3.9-bullseye, 3.8-bullseye, 3.7-bullseye, 3.6-bullseye, 3-buster, 3.10-buster, 3.9-buster, 3.8-buster, 3.7-buster, 3.6-buster
+ARG VARIANT="3.10-bullseye"
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
+# COPY requirements.txt /tmp/pip-tmp/
+# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
+#    && rm -rf /tmp/pip-tmp
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/devcontainer.json

@@ -0,0 +1,51 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.233.0/containers/python-3
+{
+	"name": "Python 3",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": "..",
+		"args": { 
+			// Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "3.10",
+			// Options
+			"NODE_VERSION": "none"
+		}
+	},
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": { 
+		"python.defaultInterpreterPath": "/usr/local/bin/python",
+		"python.linting.enabled": true,
+		"python.linting.pylintEnabled": true,
+		"python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
+		"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
+		"python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
+		"python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
+		"python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
+		"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
+		"python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
+		"python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
+		"python.linting.pylintPath": "/usr/local/py-utils/bin/pylint"
+	},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"ms-python.python",
+		"ms-python.vscode-pylance"
+	],
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "git submodule update --init && pip3 install --user -e .[dev] && pre-commit install",
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode",
+	"features": {
+		"git": "latest"
+	}
+}

.gitattributes

@@ -0,0 +1,9 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto
+
+# Explicitly declare text files you want to always be normalized and converted
+# to native line endings on checkout.
+*.py text
+*.yml text
+*.md text
+*.txt text

.github/CODE_OF_CONDUCT.md

@@ -1,46 +1,46 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
-
-[homepage]: https://contributor-covenant.org
-[version]: https://contributor-covenant.org/version/1/4/
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

.github/CONTRIBUTING.md

@@ -1,197 +1,210 @@
-# Contributing to Capa
-
-First off, thanks for taking the time to contribute!
-
-The following is a set of guidelines for contributing to capa and its packages, which are hosted in the [FireEye Organization](https://github.com/fireeye) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
-
-#### Table Of Contents
-
-[Code of Conduct](#code-of-conduct)
-
-[What should I know before I get started?](#what-should-i-know-before-i-get-started)
-  * [Capa and its Repositories](#capa-and-its-repositories)
-  * [Capa Design Decisions](#design-decisions)
-
-[How Can I Contribute?](#how-can-i-contribute)
-  * [Reporting Bugs](#reporting-bugs)
-  * [Suggesting Enhancements](#suggesting-enhancements)
-  * [Your First Code Contribution](#your-first-code-contribution)
-  * [Pull Requests](#pull-requests)
-
-[Styleguides](#styleguides)
-  * [Git Commit Messages](#git-commit-messages)
-  * [Python Styleguide](#python-styleguide)
-  * [Rules Styleguide](#rules-styleguide)
-
-## Code of Conduct
-
-This project and everyone participating in it is governed by the [Capa Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.
-
-## What should I know before I get started?
-
-### Capa and its repositories
-
-We host the capa project as three Github repositories:
-  - [capa](https://github.com/fireeye/capa)
-  - [capa-rules](https://github.com/fireeye/capa-rules)
-  - [capa-testfiles](https://github.com/fireeye/capa-testfiles)
-  
-The command line tools, logic engine, and other Python source code are found in the `capa` repository.
-This is the repository to fork when you want to enhance the features, performance, or user interface of capa.
-Do *not* push rules directly to this repository, instead...
-
-The standard rules contributed by the community are found in the `capa-rules` repository.
-When you have an idea for a new rule, you should open a PR against `capa-rules`.
-We keep `capa` and `capa-rules` separate to distinguish where ideas, bugs, and discussions should happen.
-If you're writing yaml it probably goes in `capa-rules` and if you're writing Python it probably goes in `capa`.
-Also, we encourage users to develop their own rule repositories, so we treat our default set of rules in the same way.
-
-Test fixtures, such as malware samples and analysis workspaces, are found in the `capa-testfiles` repository.
-These are files you'll need in order to run the linter (in `--thorough` mode) and full test suites;
- however, they take up a lot of space (1GB+), so by keeping `capa-testfiles` separate,
- a shallow checkout of `capa` and `capa-rules` doesn't take much bandwidth.
-
-### Design Decisions
-
-When we make a significant decision in how we maintain the project and what we can or cannot support,
- we will document it in the [capa issues tracker](https://github.com/fireeye/capa/issues).
-This is the best place review our discussions about what/how/why we do things in the project.
-If you have a question, check to see if it is documented there.
-If it is *not* documented there, or you can't find an answer, please open a issue.
-We'll link to existing issues when appropriate to keep discussions in one place.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-This section guides you through submitting a bug report for capa.
-Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
-
-Before creating bug reports, please check [this list](#before-submitting-a-bug-report)
- as you might find out that you don't need to create one.
-When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report).
-Fill out [the required template](./ISSUE_TEMPLATE/bug_report.md),
- the information it asks for helps us resolve issues faster.
-
-> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
-
-#### Before Submitting A Bug Report
-
-* **Determine [which repository the problem should be reported in](#capa-and-its-repositories)**.
-* **Perform a [cursory search](https://github.com/fireeye/capa/issues?q=is%3Aissue)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.
-
-#### How Do I Submit A (Good) Bug Report?
-
-Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/).
-After you've determined [which repository](#capa-and-its-repositories) your bug is related to,
- create an issue on that repository and provide the following information by filling in 
- [the template](./ISSUE_TEMPLATE/bug_report.md).
-
-Explain the problem and include additional details to help maintainers reproduce the problem:
-
-* **Use a clear and descriptive title** for the issue to identify the problem.
-* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining how you started capa, e.g. which command exactly you used in the terminal, or how you started capa otherwise.
-* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
-* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
-* **Explain which behavior you expected to see instead and why.**
-* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
-* **If you're reporting that capa crashed**, include the stack trace from the terminal. Include the stack trace in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist.
-* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below.
-
-Provide more context by answering these questions:
-
-* **Did the problem start happening recently** (e.g. after updating to a new version of capa) or was this always a problem?
-* If the problem started happening recently, **can you reproduce the problem in an older version of capa?** What's the most recent version in which the problem doesn't happen? You can download older versions of capa from [the releases page](https://github.com/fireeye/capa/releases).
-* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
-* If the problem is related to working with files (e.g. opening and editing files), **does the problem happen for all files and projects or only some?** Does the problem happen only when working with local or remote files (e.g. on network drives), with files of a specific type (e.g. only JavaScript or Python files), with large files or files with very long lines, or with files in a specific encoding? Is there anything else special about the files you are using?
-
-Include details about your configuration and environment:
-
-* **Which version of capa are you using?** You can get the exact version by running `capa --version` in your terminal.
-* **What's the name and version of the OS you're using**?
-
-### Suggesting Enhancements
-
-This section guides you through submitting an enhancement suggestion for capa, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
-
-Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](./ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
-
-#### Before Submitting An Enhancement Suggestion
-
-* **Determine [which repository the enhancement should be suggested in](#capa-and-its-repositories).**
-* **Perform a [cursory search](https://github.com/fireeye/capa/issues?q=is%3Aissue)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
-
-#### How Do I Submit A (Good) Enhancement Suggestion?
-
-Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which repository](#capa-and-its-repositories) your enhancement suggestion is related to, create an issue on that repository and provide the following information:
-
-* **Use a clear and descriptive title** for the issue to identify the suggestion.
-* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
-* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
-* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
-* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of capa which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
-* **Explain why this enhancement would be useful** to most capa users and isn't something that can or should be implemented as an external tool that uses capa as a library.
-* **Specify which version of capa you're using.** You can get the exact version by running `capa --version` in your terminal.
-* **Specify the name and version of the OS you're using.**
-
-### Your First Code Contribution
-
-Unsure where to begin contributing to capa? You can start by looking through these `good-first-issue` and `rule-idea` issues:
-
-* [good-first-issue](https://github.com/fireeye/capa/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - issues which should only require a few lines of code, and a test or two.
-* [rule-idea](https://github.com/fireeye/capa-rules/issues?q=is%3Aissue+is%3Aopen+label%3A%22rule+idea%22) - issues that describe potential new rule ideas.
-
-Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
-
-#### Local development
-
-capa and all its resources can be developed locally. 
-For instructions on how to do this, see the "Method 3" section of the [installation guide](https://github.com/fireeye/capa/blob/master/doc/installation.md).
-
-### Pull Requests
-
-The process described here has several goals:
-
-- Maintain capa's quality
-- Fix problems that are important to users
-- Engage the community in working toward the best possible capa
-- Enable a sustainable system for capa's maintainers to review contributions
-
-Please follow these steps to have your contribution considered by the maintainers:
-
-1. Follow all instructions in [the template](PULL_REQUEST_TEMPLATE.md)
-2. Follow the [styleguides](#styleguides)
-3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing? </summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
-
-While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
-
-## Styleguides
-
-### Git Commit Messages
-
-* Use the present tense ("Add feature" not "Added feature")
-* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
-* Prefix the first line with the component in question ("rules: ..." or "render: ...")
-* Reference issues and pull requests liberally after the first line
-
-### Python Styleguide
-
-All Python code must adhere to the style guide used by capa: 
-
-  1. [PEP8](https://www.python.org/dev/peps/pep-0008/), with clarifications from
-  2. [Willi's style guide](https://docs.google.com/document/d/1iRpeg-w4DtibwytUyC_dDT7IGhNGBP25-nQfuBa-Fyk/edit?usp=sharing), formatted with
-  3. [isort](https://pypi.org/project/isort/) (with line width 120 and ordered by line length), and formatted with
-  4. [black](https://github.com/psf/black) (with line width 120), and formatted with
-  5. [dos2unix](https://linux.die.net/man/1/dos2unix)
-  
-Our CI pipeline will reformat and enforce the Python styleguide.
- 
-### Rules Styleguide
-
-All (non-nursery) capa rules must:
-
-  1. pass the [linter](https://github.com/fireeye/capa/blob/master/scripts/lint.py), and
-  2. be formatted with [capafmt](https://github.com/fireeye/capa/blob/master/scripts/capafmt.py)
-  
-This ensures that all rules meet the same minimum level of quality and are structured in a consistent way.
-Our CI pipeline will reformat and enforce the capa rules styleguide.
+# Contributing to Capa
+
+First off, thanks for taking the time to contribute!
+
+The following is a set of guidelines for contributing to capa and its packages, which are hosted in the [Mandiant Organization](https://github.com/mandiant) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+#### Table Of Contents
+
+[Code of Conduct](#code-of-conduct)
+
+[What should I know before I get started?](#what-should-i-know-before-i-get-started)
+  * [Capa and its Repositories](#capa-and-its-repositories)
+  * [Capa Design Decisions](#design-decisions)
+
+[How Can I Contribute?](#how-can-i-contribute)
+  * [Reporting Bugs](#reporting-bugs)
+  * [Suggesting Enhancements](#suggesting-enhancements)
+  * [Your First Code Contribution](#your-first-code-contribution)
+  * [Pull Requests](#pull-requests)
+
+[Styleguides](#styleguides)
+  * [Git Commit Messages](#git-commit-messages)
+  * [Python Styleguide](#python-styleguide)
+  * [Rules Styleguide](#rules-styleguide)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the [Capa Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.
+
+## What should I know before I get started?
+
+### Capa and its repositories
+
+We host the capa project as three GitHub repositories:
+  - [capa](https://github.com/mandiant/capa)
+  - [capa-rules](https://github.com/mandiant/capa-rules)
+  - [capa-testfiles](https://github.com/mandiant/capa-testfiles)
+  
+The command line tools, logic engine, and other Python source code are found in the `capa` repository.
+This is the repository to fork when you want to enhance the features, performance, or user interface of capa.
+Do *not* push rules directly to this repository, instead...
+
+The standard rules contributed by the community are found in the `capa-rules` repository.
+When you have an idea for a new rule, you should open a PR against `capa-rules`.
+We keep `capa` and `capa-rules` separate to distinguish where ideas, bugs, and discussions should happen.
+If you're writing yaml it probably goes in `capa-rules` and if you're writing Python it probably goes in `capa`.
+Also, we encourage users to develop their own rule repositories, so we treat our default set of rules in the same way.
+
+Test fixtures, such as malware samples and analysis workspaces, are found in the `capa-testfiles` repository.
+These are files you'll need in order to run the linter (in `--thorough` mode) and full test suites;
+ however, they take up a lot of space (1GB+), so by keeping `capa-testfiles` separate,
+ a shallow checkout of `capa` and `capa-rules` doesn't take much bandwidth.
+
+### Design Decisions
+
+When we make a significant decision in how we maintain the project and what we can or cannot support,
+ we will document it in the [capa issues tracker](https://github.com/mandiant/capa/issues).
+This is the best place review our discussions about what/how/why we do things in the project.
+If you have a question, check to see if it is documented there.
+If it is *not* documented there, or you can't find an answer, please open a issue.
+We'll link to existing issues when appropriate to keep discussions in one place.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+This section guides you through submitting a bug report for capa.
+Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
+
+Before creating bug reports, please check [this list](#before-submitting-a-bug-report)
+ as you might find out that you don't need to create one.
+When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report).
+Fill out [the required template](./ISSUE_TEMPLATE/bug_report.md),
+ the information it asks for helps us resolve issues faster.
+
+> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
+
+#### Before Submitting A Bug Report
+
+* **Determine [which repository the problem should be reported in](#capa-and-its-repositories)**.
+* **Perform a [cursory search](https://github.com/mandiant/capa/issues?q=is%3Aissue)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.
+
+#### How Do I Submit A (Good) Bug Report?
+
+Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/).
+After you've determined [which repository](#capa-and-its-repositories) your bug is related to,
+ create an issue on that repository and provide the following information by filling in 
+ [the template](./ISSUE_TEMPLATE/bug_report.md).
+
+Explain the problem and include additional details to help maintainers reproduce the problem:
+
+* **Use a clear and descriptive title** for the issue to identify the problem.
+* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining how you started capa, e.g. which command exactly you used in the terminal, or how you started capa otherwise.
+* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
+* **Explain which behavior you expected to see instead and why.**
+* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
+* **If you're reporting that capa crashed**, include the stack trace from the terminal. Include the stack trace in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist.
+* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below.
+
+Provide more context by answering these questions:
+
+* **Did the problem start happening recently** (e.g. after updating to a new version of capa) or was this always a problem?
+* If the problem started happening recently, **can you reproduce the problem in an older version of capa?** What's the most recent version in which the problem doesn't happen? You can download older versions of capa from [the releases page](https://github.com/mandiant/capa/releases).
+* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
+* If the problem is related to working with files (e.g. opening and editing files), **does the problem happen for all files and projects or only some?** Does the problem happen only when working with local or remote files (e.g. on network drives), with files of a specific type (e.g. only JavaScript or Python files), with large files or files with very long lines, or with files in a specific encoding? Is there anything else special about the files you are using?
+
+Include details about your configuration and environment:
+
+* **Which version of capa are you using?** You can get the exact version by running `capa --version` in your terminal.
+* **What's the name and version of the OS you're using**?
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion for capa, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
+
+Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](./ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
+
+#### Before Submitting An Enhancement Suggestion
+
+* **Determine [which repository the enhancement should be suggested in](#capa-and-its-repositories).**
+* **Perform a [cursory search](https://github.com/mandiant/capa/issues?q=is%3Aissue)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+
+#### How Do I Submit A (Good) Enhancement Suggestion?
+
+Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which repository](#capa-and-its-repositories) your enhancement suggestion is related to, create an issue on that repository and provide the following information:
+
+* **Use a clear and descriptive title** for the issue to identify the suggestion.
+* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
+* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
+* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of capa which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
+* **Explain why this enhancement would be useful** to most capa users and isn't something that can or should be implemented as an external tool that uses capa as a library.
+* **Specify which version of capa you're using.** You can get the exact version by running `capa --version` in your terminal.
+* **Specify the name and version of the OS you're using.**
+
+### Your First Code Contribution
+
+Unsure where to begin contributing to capa? You can start by looking through these `good-first-issue` and `rule-idea` issues:
+
+* [good-first-issue](https://github.com/mandiant/capa/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - issues which should only require a few lines of code, and a test or two.
+* [rule-idea](https://github.com/mandiant/capa-rules/issues?q=is%3Aissue+is%3Aopen+label%3A%22rule+idea%22) - issues that describe potential new rule ideas.
+
+Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
+
+#### Local development
+
+capa and all its resources can be developed locally. 
+For instructions on how to do this, see the "Method 3" section of the [installation guide](https://github.com/mandiant/capa/blob/master/doc/installation.md).
+
+### Pull Requests
+
+The process described here has several goals:
+
+- Maintain capa's quality
+- Fix problems that are important to users
+- Engage the community in working toward the best possible capa
+- Enable a sustainable system for capa's maintainers to review contributions
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+0. Sign the [Contributor License Agreement](#contributor-license-agreement)
+1. Follow the [styleguides](#styleguides)
+2. Update the CHANGELOG and add tests and documentation. In case they are not needed, indicate it in [the PR template](pull_request_template.md).
+3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing? </summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
+
+While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
+
+### Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution,
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Styleguides
+
+### Git Commit Messages
+
+* Use the present tense ("Add feature" not "Added feature")
+* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+* Prefix the first line with the component in question ("rules: ..." or "render: ...")
+* Reference issues and pull requests liberally after the first line
+
+### Python Styleguide
+
+All Python code must adhere to the style guide used by capa: 
+
+  1. [PEP8](https://www.python.org/dev/peps/pep-0008/), with clarifications from
+  2. [Willi's style guide](https://docs.google.com/document/d/1iRpeg-w4DtibwytUyC_dDT7IGhNGBP25-nQfuBa-Fyk/edit?usp=sharing), formatted with
+  3. [isort](https://pypi.org/project/isort/) (with line width 120 and ordered by line length), and formatted with
+  4. [black](https://github.com/psf/black) (with line width 120), and formatted with
+  5. [dos2unix](https://linux.die.net/man/1/dos2unix)
+  
+Our CI pipeline will reformat and enforce the Python styleguide.
+ 
+### Rules Styleguide
+
+All (non-nursery) capa rules must:
+
+  1. pass the [linter](https://github.com/mandiant/capa/blob/master/scripts/lint.py), and
+  2. be formatted with [capafmt](https://github.com/mandiant/capa/blob/master/scripts/capafmt.py)
+  
+This ensures that all rules meet the same minimum level of quality and are structured in a consistent way.
+Our CI pipeline will reformat and enforce the capa rules styleguide.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,47 +1,47 @@
----
-name: Bug report
-about: Create a report to help us improve
-
----
-
-<!--
-
-Have you read capa's Code of Conduct? By filing an Issue, you are expected to comply with it, including treating everyone with respect: https://github.com/fireeye/capa/blob/master/.github/CODE_OF_CONDUCT.md
--->
-
-### Prerequisites
-
-* [ ] Put an X between the brackets on this line if you have done all of the following:
-    * Checked that your issue isn't already filed: [search](https://github.com/fireeye/capa/issues?q=is%3Aissue+is%3Aopen+)
-
-### Description
-
-<!-- Description of the issue -->
-
-### Steps to Reproduce
-
-1. <!-- First Step -->
-2. <!-- Second Step -->
-3. <!-- and so on… -->
-
-**Expected behavior:**
-
-<!-- What you expect to happen -->
-
-**Actual behavior:**
-
-<!-- What actually happens -->
-
-**Reproduces how often:**
-
-<!-- What percentage of the time does it reproduce? -->
-
-### Versions
-
-<!-- You can get this information from copy and pasting the output of `capa --version` from the command line.
- Please specify the component you're using (e.g. standalone tool or IDA Pro integration) and your Python version.
- Also, please include the OS and what version of the OS you're running. -->
-
-### Additional Information
-
-<!-- Any additional information, configuration or data that might be necessary to reproduce the issue. -->
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+<!--
+# Is your bug report related to capa rules (for example a false positive)?
+We use submodules to separate code, rules and test data. If your issue is related to capa rules, please report it at https://github.com/mandiant/capa-rules/issues.
+
+# Have you checked that your issue isn't already filed?
+Please search if there is a similar issue at https://github.com/mandiant/capa/issues. If there is already a similar issue, please add more details there instead of opening a new one.
+
+# Have you read capa's Code of Conduct?
+By filing an Issue, you are expected to comply with it, including treating everyone with respect: https://github.com/mandiant/capa/blob/master/.github/CODE_OF_CONDUCT.md
+
+# Have you read capa's CONTRIBUTING guide?
+It contains helpful information about how to contribute to capa. Check https://github.com/mandiant/capa/blob/master/.github/CONTRIBUTING.md#reporting-bugs
+-->
+
+### Description
+
+<!-- Description of the issue -->
+
+### Steps to Reproduce
+
+<!-- 1. First Step -->
+<!-- 2. Second Step -->
+<!-- 3. and so on… -->
+
+**Expected behavior:**
+
+<!-- What you expect to happen -->
+
+**Actual behavior:**
+
+<!-- What actually happens -->
+
+### Versions
+
+<!-- You can get this information from copy and pasting the output of `capa --version` from the command line.
+ Please specify the component you're using (e.g. standalone tool or IDA Pro integration) and your Python version.
+ Also, please include the OS and what version of the OS you're running. -->
+
+### Additional Information
+
+<!-- Any additional information, configuration or data that might be necessary to reproduce the issue. -->
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,26 +1,35 @@
----
-name: Feature request
-about: Suggest an idea for capa
-
----
-
-<!--
-
-Have you read capa's Code of Conduct? By filing an Issue, you are expected to comply with it, including treating everyone with respect: https://github.com/fireeye/capa/blob/master/CODE_OF_CONDUCT.md
--->
-
-## Summary
-
-<!-- One paragraph explanation of the feature. -->
-
-## Motivation
-
-<!-- Why are we doing this? What use cases does it support? What is the expected outcome? -->
-
-## Describe alternatives you've considered
-
-<!-- A clear and concise description of the alternative solutions you've considered. -->
-
-## Additional context
-
-<!-- Add any other context or screenshots about the feature request here. -->
+---
+name: Feature request
+about: Suggest an idea for capa
+
+---
+<!--
+# Is your issue related to capa rules (for example an idea for a new rule)?
+We use submodules to separate code, rules and test data. If your issue is related to capa rules, please report it at https://github.com/mandiant/capa-rules/issues.
+
+# Have you checked that your issue isn't already filed?
+Please search if there is a similar issue at https://github.com/mandiant/capa/issues. If there is already a similar issue, please add more details there instead of opening a new one.
+
+# Have you read capa's Code of Conduct?
+By filing an Issue, you are expected to comply with it, including treating everyone with respect: https://github.com/mandiant/capa/blob/master/.github/CODE_OF_CONDUCT.md
+
+# Have you read capa's CONTRIBUTING guide?
+It contains helpful information about how to contribute to capa. Check https://github.com/mandiant/capa/blob/master/.github/CONTRIBUTING.md#suggesting-enhancements
+-->
+
+### Summary
+
+<!-- One paragraph explanation of the feature. -->
+
+### Motivation
+
+<!-- Why are we doing this? What use cases does it support? What is the expected outcome? -->
+
+### Describe alternatives you've considered
+
+<!-- A clear and concise description of the alternative solutions you've considered. -->
+
+## Additional context
+
+<!-- Add any other context or screenshots about the feature request here. -->
+

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/flake8.ini

@@ -0,0 +1,41 @@
+[flake8]
+max-line-length = 120
+
+extend-ignore =
+    # E203: whitespace before ':'  (black does this)
+    E203,
+    # F401: `foo` imported but unused  (prefer ruff)
+    F401,
+    # F811 Redefinition of unused `foo`  (prefer ruff)
+    F811,
+    # E501 line too long  (prefer black)
+    E501,
+    # B010 Do not call setattr with a constant attribute value
+    B010,
+    # G200 Logging statement uses exception in arguments
+    G200,
+    # SIM102 Use a single if-statement instead of nested if-statements
+    # doesn't provide a space for commenting or logical separation of conditions
+    SIM102,
+    # SIM114 Use logical or and a single body
+    # makes logic trees too complex
+    SIM114,
+    # SIM117 Use 'with Foo, Bar:' instead of multiple with statements
+    # makes lines too long
+    SIM117
+
+per-file-ignores =
+    # T201 print found.
+    #
+    # scripts are meant to print output
+    scripts/*: T201
+    # capa.exe is meant to print output
+    capa/main.py: T201
+    # IDA tests emit results to output window so need to print
+    tests/test_ida_features.py: T201
+    # utility used to find the Binary Ninja API via invoking python.exe
+    capa/features/extractors/binja/find_binja_api.py: T201
+
+copyright-check = True
+copyright-min-file-size = 1 
+copyright-regexp = Copyright \(C\) 2023 Mandiant, Inc. All Rights Reserved.

.github/mypy/mypy.ini

@@ -0,0 +1,88 @@
+[mypy]
+
+[mypy-halo.*]
+ignore_missing_imports = True
+
+[mypy-tqdm.*]
+ignore_missing_imports = True
+
+[mypy-ruamel.*]
+ignore_missing_imports = True
+
+[mypy-networkx.*]
+ignore_missing_imports = True
+
+[mypy-pefile.*]
+ignore_missing_imports = True
+
+[mypy-viv_utils.*]
+ignore_missing_imports = True
+
+[mypy-flirt.*]
+ignore_missing_imports = True
+
+[mypy-lief.*]
+ignore_missing_imports = True
+
+[mypy-idc.*]
+ignore_missing_imports = True
+
+[mypy-vivisect.*]
+ignore_missing_imports = True
+
+[mypy-envi.*]
+ignore_missing_imports = True
+
+[mypy-PE.*]
+ignore_missing_imports = True
+
+[mypy-idaapi.*]
+ignore_missing_imports = True
+
+[mypy-idautils.*]
+ignore_missing_imports = True
+
+[mypy-ida_auto.*]
+ignore_missing_imports = True
+
+[mypy-ida_bytes.*]
+ignore_missing_imports = True
+
+[mypy-ida_nalt.*]
+ignore_missing_imports = True
+
+[mypy-ida_kernwin.*]
+ignore_missing_imports = True
+
+[mypy-ida_settings.*]
+ignore_missing_imports = True
+
+[mypy-ida_funcs.*]
+ignore_missing_imports = True
+
+[mypy-ida_loader.*]
+ignore_missing_imports = True
+
+[mypy-ida_segment.*]
+ignore_missing_imports = True
+
+[mypy-PyQt5.*]
+ignore_missing_imports = True
+
+[mypy-binaryninja.*]
+ignore_missing_imports = True
+
+[mypy-pytest.*]
+ignore_missing_imports = True
+
+[mypy-devtools.*]
+ignore_missing_imports = True
+
+[mypy-elftools.*]
+ignore_missing_imports = True
+
+[mypy-dncil.*]
+ignore_missing_imports = True
+
+[mypy-netnode.*]
+ignore_missing_imports = True

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+
+<!--
+Thank you for contributing to capa! <3
+
+Please read capa's CONTRIBUTING guide if you haven't done so already.
+It contains helpful information about how to contribute to capa. Check https://github.com/mandiant/capa/blob/master/.github/CONTRIBUTING.md
+
+Please describe the changes in this pull request (PR). Include your motivation and context to help us review.
+
+Please mention the issue your PR addresses (if any):
+closes #issue_number
+-->
+
+
+### Checklist
+
+<!-- CHANGELOG.md has a `master (unreleased)` section. Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning in the release notes to this file. -->
+- [ ] No CHANGELOG update needed
+<!-- Tests prove that your fix/work as expected and ensure it doesn't break on the feature. -->
+- [ ] No new tests needed
+<!-- Please help us keeping capa documentation up-to-date -->
+- [ ] No documentation update needed

.github/pyinstaller/hooks/hook-vivisect.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2020 Mandiant, Inc. All Rights Reserved.
 
 from PyInstaller.utils.hooks import copy_metadata
 
@@ -13,3 +13,173 @@ from PyInstaller.utils.hooks import copy_metadata
 #
 # ref: https://github.com/pyinstaller/pyinstaller/issues/1713#issuecomment-162682084
 datas = copy_metadata("vivisect")
+
+excludedimports = [
+    # viv gui requires these heavy libraries,
+    # but viv as a library doesn't.
+    # they shouldn't be installed in our configuration,
+    # but we'll ensure they don't slip in here (such as on developers' systems).
+    "PyQt5",
+    "qt5",
+    "pyqtwebengine",
+    # the above are imported by these viv modules.
+    # so really, we'd want to exclude these submodules of viv.
+    # but i dont think this works.
+    "vqt",
+    "vdb.qt",
+    "envi.qt",
+    # unused by capa
+    "pyasn1",
+]
+
+hiddenimports = [
+    # vivisect does manual/runtime importing of its modules,
+    # so declare the things that could be imported here.
+    "vivisect",
+    "vivisect.analysis",
+    "vivisect.analysis.amd64",
+    "vivisect.analysis.amd64.emulation",
+    "vivisect.analysis.amd64.golang",
+    "vivisect.analysis.crypto",
+    "vivisect.analysis.crypto.constants",
+    "vivisect.analysis.elf",
+    "vivisect.analysis.elf.elfplt",
+    "vivisect.analysis.elf.elfplt_late",
+    "vivisect.analysis.elf.libc_start_main",
+    "vivisect.analysis.generic",
+    "vivisect.analysis.generic.codeblocks",
+    "vivisect.analysis.generic.emucode",
+    "vivisect.analysis.generic.entrypoints",
+    "vivisect.analysis.generic.funcentries",
+    "vivisect.analysis.generic.impapi",
+    "vivisect.analysis.generic.linker",
+    "vivisect.analysis.generic.mkpointers",
+    "vivisect.analysis.generic.noret",
+    "vivisect.analysis.generic.pointers",
+    "vivisect.analysis.generic.pointertables",
+    "vivisect.analysis.generic.relocations",
+    "vivisect.analysis.generic.strconst",
+    "vivisect.analysis.generic.switchcase",
+    "vivisect.analysis.generic.symswitchcase",
+    "vivisect.analysis.generic.thunks",
+    "vivisect.analysis.i386",
+    "vivisect.analysis.i386.calling",
+    "vivisect.analysis.i386.golang",
+    "vivisect.analysis.i386.importcalls",
+    "vivisect.analysis.i386.instrhook",
+    "vivisect.analysis.i386.thunk_reg",
+    "vivisect.analysis.ms",
+    "vivisect.analysis.ms.hotpatch",
+    "vivisect.analysis.ms.localhints",
+    "vivisect.analysis.ms.msvc",
+    "vivisect.analysis.ms.msvcfunc",
+    "vivisect.analysis.ms.vftables",
+    "vivisect.analysis.pe",
+    "vivisect.impapi.posix.amd64",
+    "vivisect.impapi.posix.i386",
+    "vivisect.impapi.windows",
+    "vivisect.impapi.windows.advapi_32",
+    "vivisect.impapi.windows.advapi_64",
+    "vivisect.impapi.windows.amd64",
+    "vivisect.impapi.windows.gdi_32",
+    "vivisect.impapi.windows.gdi_64",
+    "vivisect.impapi.windows.i386",
+    "vivisect.impapi.windows.kernel_32",
+    "vivisect.impapi.windows.kernel_64",
+    "vivisect.impapi.windows.msvcr100_32",
+    "vivisect.impapi.windows.msvcr100_64",
+    "vivisect.impapi.windows.msvcr110_32",
+    "vivisect.impapi.windows.msvcr110_64",
+    "vivisect.impapi.windows.msvcr120_32",
+    "vivisect.impapi.windows.msvcr120_64",
+    "vivisect.impapi.windows.msvcr71_32",
+    "vivisect.impapi.windows.msvcr80_32",
+    "vivisect.impapi.windows.msvcr80_64",
+    "vivisect.impapi.windows.msvcr90_32",
+    "vivisect.impapi.windows.msvcr90_64",
+    "vivisect.impapi.windows.msvcrt_32",
+    "vivisect.impapi.windows.msvcrt_64",
+    "vivisect.impapi.windows.ntdll_32",
+    "vivisect.impapi.windows.ntdll_64",
+    "vivisect.impapi.windows.ole_32",
+    "vivisect.impapi.windows.ole_64",
+    "vivisect.impapi.windows.rpcrt4_32",
+    "vivisect.impapi.windows.rpcrt4_64",
+    "vivisect.impapi.windows.shell_32",
+    "vivisect.impapi.windows.shell_64",
+    "vivisect.impapi.windows.user_32",
+    "vivisect.impapi.windows.user_64",
+    "vivisect.impapi.windows.ws2plus_32",
+    "vivisect.impapi.windows.ws2plus_64",
+    "vivisect.impapi.winkern",
+    "vivisect.impapi.winkern.i386",
+    "vivisect.impapi.winkern.amd64",
+    "vivisect.parsers.blob",
+    "vivisect.parsers.elf",
+    "vivisect.parsers.ihex",
+    "vivisect.parsers.macho",
+    "vivisect.parsers.pe",
+    "vivisect.storage",
+    "vivisect.storage.basicfile",
+    "vstruct.constants",
+    "vstruct.constants.ntstatus",
+    "vstruct.defs",
+    "vstruct.defs.arm7",
+    "vstruct.defs.bmp",
+    "vstruct.defs.dns",
+    "vstruct.defs.elf",
+    "vstruct.defs.gif",
+    "vstruct.defs.ihex",
+    "vstruct.defs.inet",
+    "vstruct.defs.java",
+    "vstruct.defs.kdcom",
+    "vstruct.defs.macho",
+    "vstruct.defs.macho.const",
+    "vstruct.defs.macho.fat",
+    "vstruct.defs.macho.loader",
+    "vstruct.defs.macho.stabs",
+    "vstruct.defs.minidump",
+    "vstruct.defs.pcap",
+    "vstruct.defs.pe",
+    "vstruct.defs.pptp",
+    "vstruct.defs.rar",
+    "vstruct.defs.swf",
+    "vstruct.defs.win32",
+    "vstruct.defs.windows",
+    "vstruct.defs.windows.win_5_1_i386",
+    "vstruct.defs.windows.win_5_1_i386.ntdll",
+    "vstruct.defs.windows.win_5_1_i386.ntoskrnl",
+    "vstruct.defs.windows.win_5_1_i386.win32k",
+    "vstruct.defs.windows.win_5_2_i386",
+    "vstruct.defs.windows.win_5_2_i386.ntdll",
+    "vstruct.defs.windows.win_5_2_i386.ntoskrnl",
+    "vstruct.defs.windows.win_5_2_i386.win32k",
+    "vstruct.defs.windows.win_6_1_amd64",
+    "vstruct.defs.windows.win_6_1_amd64.ntdll",
+    "vstruct.defs.windows.win_6_1_amd64.ntoskrnl",
+    "vstruct.defs.windows.win_6_1_amd64.win32k",
+    "vstruct.defs.windows.win_6_1_i386",
+    "vstruct.defs.windows.win_6_1_i386.ntdll",
+    "vstruct.defs.windows.win_6_1_i386.ntoskrnl",
+    "vstruct.defs.windows.win_6_1_i386.win32k",
+    "vstruct.defs.windows.win_6_1_wow64",
+    "vstruct.defs.windows.win_6_1_wow64.ntdll",
+    "vstruct.defs.windows.win_6_2_amd64",
+    "vstruct.defs.windows.win_6_2_amd64.ntdll",
+    "vstruct.defs.windows.win_6_2_amd64.ntoskrnl",
+    "vstruct.defs.windows.win_6_2_amd64.win32k",
+    "vstruct.defs.windows.win_6_2_i386",
+    "vstruct.defs.windows.win_6_2_i386.ntdll",
+    "vstruct.defs.windows.win_6_2_i386.ntoskrnl",
+    "vstruct.defs.windows.win_6_2_i386.win32k",
+    "vstruct.defs.windows.win_6_2_wow64",
+    "vstruct.defs.windows.win_6_2_wow64.ntdll",
+    "vstruct.defs.windows.win_6_3_amd64",
+    "vstruct.defs.windows.win_6_3_amd64.ntdll",
+    "vstruct.defs.windows.win_6_3_amd64.ntoskrnl",
+    "vstruct.defs.windows.win_6_3_i386",
+    "vstruct.defs.windows.win_6_3_i386.ntdll",
+    "vstruct.defs.windows.win_6_3_i386.ntoskrnl",
+    "vstruct.defs.windows.win_6_3_wow64",
+    "vstruct.defs.windows.win_6_3_wow64.ntdll",
+]

.github/pyinstaller/pyinstaller.spec

@@ -1,167 +1,40 @@
 # -*- mode: python -*-
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2020 Mandiant, Inc. All Rights Reserved.
 import os.path
 import subprocess
 
 import wcwidth
 
 
-# when invoking pyinstaller from the project root,
-# this gets run from the project root.
-with open('./capa/version.py', 'wb') as f:
-    f.write("__version__ = '%s'"
-            % subprocess.check_output(["git", "describe", "--always"]).strip())
-
 a = Analysis(
     # when invoking pyinstaller from the project root,
     # this gets invoked from the directory of the spec file,
     # i.e. ./.github/pyinstaller
-    ['../../capa/main.py'],
-    pathex=['capa'],
+    ["../../capa/main.py"],
+    pathex=["capa"],
     binaries=None,
     datas=[
         # when invoking pyinstaller from the project root,
         # this gets invoked from the directory of the spec file,
         # i.e. ./.github/pyinstaller
-        ('../../rules', 'rules'),
-
+        ("../../rules", "rules"),
+        ("../../sigs", "sigs"),
+        ("../../cache", "cache"),
         # capa.render.default uses tabulate that depends on wcwidth.
         # it seems wcwidth uses a json file `version.json`
         # and this doesn't get picked up by pyinstaller automatically.
         # so we manually embed the wcwidth resources here.
         #
         # ref: https://stackoverflow.com/a/62278462/87207
-        (os.path.dirname(wcwidth.__file__), 'wcwidth')
-    ],
-    hiddenimports=[
-        # vivisect does manual/runtime importing of its modules,
-        # so declare the things that could be imported here.
-        "pycparser",
-        "vivisect",
-        "vivisect.analysis",
-        "vivisect.analysis.amd64",
-        "vivisect.analysis.amd64",
-        "vivisect.analysis.amd64.emulation",
-        "vivisect.analysis.amd64.golang",
-        "vivisect.analysis.crypto",
-        "vivisect.analysis.crypto",
-        "vivisect.analysis.crypto.constants",
-        "vivisect.analysis.elf",
-        "vivisect.analysis.elf",
-        "vivisect.analysis.elf.elfplt",
-        "vivisect.analysis.elf.libc_start_main",
-        "vivisect.analysis.generic",
-        "vivisect.analysis.generic",
-        "vivisect.analysis.generic.codeblocks",
-        "vivisect.analysis.generic.emucode",
-        "vivisect.analysis.generic.entrypoints",
-        "vivisect.analysis.generic.funcentries",
-        "vivisect.analysis.generic.impapi",
-        "vivisect.analysis.generic.mkpointers",
-        "vivisect.analysis.generic.pointers",
-        "vivisect.analysis.generic.pointertables",
-        "vivisect.analysis.generic.relocations",
-        "vivisect.analysis.generic.strconst",
-        "vivisect.analysis.generic.switchcase",
-        "vivisect.analysis.generic.thunks",
-        "vivisect.analysis.i386",
-        "vivisect.analysis.i386",
-        "vivisect.analysis.i386.calling",
-        "vivisect.analysis.i386.golang",
-        "vivisect.analysis.i386.importcalls",
-        "vivisect.analysis.i386.instrhook",
-        "vivisect.analysis.i386.thunk_bx",
-        "vivisect.analysis.ms",
-        "vivisect.analysis.ms",
-        "vivisect.analysis.ms.hotpatch",
-        "vivisect.analysis.ms.localhints",
-        "vivisect.analysis.ms.msvc",
-        "vivisect.analysis.ms.msvcfunc",
-        "vivisect.analysis.ms.vftables",
-        "vivisect.analysis.pe",
-        "vivisect.impapi.posix.amd64",
-        "vivisect.impapi.posix.i386",
-        "vivisect.impapi.windows",
-        "vivisect.impapi.windows.amd64",
-        "vivisect.impapi.windows.i386",
-        "vivisect.parsers.blob",
-        "vivisect.parsers.elf",
-        "vivisect.parsers.ihex",
-        "vivisect.parsers.macho",
-        "vivisect.parsers.parse_pe",
-        "vivisect.parsers.utils",
-        "vivisect.storage",
-        "vivisect.storage.basicfile",
-        "vstruct.constants",
-        "vstruct.constants.ntstatus",
-        "vstruct.defs",
-        "vstruct.defs.arm7",
-        "vstruct.defs.bmp",
-        "vstruct.defs.dns",
-        "vstruct.defs.elf",
-        "vstruct.defs.gif",
-        "vstruct.defs.ihex",
-        "vstruct.defs.inet",
-        "vstruct.defs.java",
-        "vstruct.defs.kdcom",
-        "vstruct.defs.macho",
-        "vstruct.defs.macho.const",
-        "vstruct.defs.macho.fat",
-        "vstruct.defs.macho.loader",
-        "vstruct.defs.macho.stabs",
-        "vstruct.defs.minidump",
-        "vstruct.defs.pcap",
-        "vstruct.defs.pe",
-        "vstruct.defs.pptp",
-        "vstruct.defs.rar",
-        "vstruct.defs.swf",
-        "vstruct.defs.win32",
-        "vstruct.defs.windows",
-        "vstruct.defs.windows.win_5_1_i386",
-        "vstruct.defs.windows.win_5_1_i386.ntdll",
-        "vstruct.defs.windows.win_5_1_i386.ntoskrnl",
-        "vstruct.defs.windows.win_5_1_i386.win32k",
-        "vstruct.defs.windows.win_5_2_i386",
-        "vstruct.defs.windows.win_5_2_i386.ntdll",
-        "vstruct.defs.windows.win_5_2_i386.ntoskrnl",
-        "vstruct.defs.windows.win_5_2_i386.win32k",
-        "vstruct.defs.windows.win_6_1_amd64",
-        "vstruct.defs.windows.win_6_1_amd64.ntdll",
-        "vstruct.defs.windows.win_6_1_amd64.ntoskrnl",
-        "vstruct.defs.windows.win_6_1_amd64.win32k",
-        "vstruct.defs.windows.win_6_1_i386",
-        "vstruct.defs.windows.win_6_1_i386.ntdll",
-        "vstruct.defs.windows.win_6_1_i386.ntoskrnl",
-        "vstruct.defs.windows.win_6_1_i386.win32k",
-        "vstruct.defs.windows.win_6_1_wow64",
-        "vstruct.defs.windows.win_6_1_wow64.ntdll",
-        "vstruct.defs.windows.win_6_2_amd64",
-        "vstruct.defs.windows.win_6_2_amd64.ntdll",
-        "vstruct.defs.windows.win_6_2_amd64.ntoskrnl",
-        "vstruct.defs.windows.win_6_2_amd64.win32k",
-        "vstruct.defs.windows.win_6_2_i386",
-        "vstruct.defs.windows.win_6_2_i386.ntdll",
-        "vstruct.defs.windows.win_6_2_i386.ntoskrnl",
-        "vstruct.defs.windows.win_6_2_i386.win32k",
-        "vstruct.defs.windows.win_6_2_wow64",
-        "vstruct.defs.windows.win_6_2_wow64.ntdll",
-        "vstruct.defs.windows.win_6_3_amd64",
-        "vstruct.defs.windows.win_6_3_amd64.ntdll",
-        "vstruct.defs.windows.win_6_3_amd64.ntoskrnl",
-        "vstruct.defs.windows.win_6_3_i386",
-        "vstruct.defs.windows.win_6_3_i386.ntdll",
-        "vstruct.defs.windows.win_6_3_i386.ntoskrnl",
-        "vstruct.defs.windows.win_6_3_wow64",
-        "vstruct.defs.windows.win_6_3_wow64.ntdll",
+        (os.path.dirname(wcwidth.__file__), "wcwidth"),
     ],
     # when invoking pyinstaller from the project root,
     # this gets run from the project root.
-    hookspath=['.github/pyinstaller/hooks'],
+    hookspath=[".github/pyinstaller/hooks"],
     runtime_hooks=None,
     excludes=[
         # ignore packages that would otherwise be bundled with the .exe.
         # review: build/pyinstaller/xref-pyinstaller.html
-
         # we don't do any GUI stuff, so ignore these modules
         "tkinter",
         "_tkinter",
@@ -171,35 +44,52 @@ a = Analysis(
         # since we don't spawn a notebook, we can safely remove these.
         "IPython",
         "ipywidgets",
-    ])
+        # these are pulled in by networkx
+        # but we don't need to compute the strongly connected components.
+        "numpy",
+        "scipy",
+        "matplotlib",
+        "pandas",
+        "pytest",
+        # deps from viv that we don't use.
+        # this duplicates the entries in `hook-vivisect`,
+        # but works better this way.
+        "vqt",
+        "vdb.qt",
+        "envi.qt",
+        "PyQt5",
+        "qt5",
+        "pyqtwebengine",
+        "pyasn1",
+        "binaryninja",
+    ],
+)
 
-a.binaries = a.binaries - TOC([
- ('tcl85.dll', None, None),
- ('tk85.dll', None, None),
- ('_tkinter', None, None)])
+a.binaries = a.binaries - TOC([("tcl85.dll", None, None), ("tk85.dll", None, None), ("_tkinter", None, None)])
 
 pyz = PYZ(a.pure, a.zipped_data)
 
-exe = EXE(pyz,
-          a.scripts,
-          a.binaries,
-          a.zipfiles,
-          a.datas,
-          exclude_binaries=False,
-          name='capa',
-          icon='logo.ico',
-          debug=False,
-          strip=None,
-          upx=True,
-          console=True )
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    exclude_binaries=False,
+    name="capa",
+    icon="logo.ico",
+    debug=False,
+    strip=None,
+    upx=True,
+    console=True,
+)
 
 # enable the following to debug the contents of the .exe
 #
-#coll = COLLECT(exe,
+# coll = COLLECT(exe,
 #               a.binaries,
 #               a.zipfiles,
 #               a.datas,
 #               strip=None,
 #               upx=True,
 #               name='capa-dat')
-

.github/ruff.toml

@@ -0,0 +1,43 @@
+# Enable the pycodestyle (`E`) and Pyflakes (`F`) rules by default.
+# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
+# McCabe complexity (`C901`) by default.
+select = ["E", "F"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# E402 module level import not at top of file
+# E722 do not use bare 'except'
+# E501 line too long
+ignore = ["E402", "E722", "E501"]
+
+line-length = 120
+
+exclude = [
+    # Exclude a variety of commonly ignored directories.
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+    # protobuf generated files
+    "*_pb2.py", 
+    "*_pb2.pyi"
+]

.github/tox.ini

@@ -1,10 +0,0 @@
-[pycodestyle]
-; E402: module level import not at top of file
-; W503: line break before binary operator
-; E231 missing whitespace after ',' (emitted by black)
-; E203 whitespace before ':' (emitted by black)
-ignore = E402,W503,E203,E231
-max-line-length = 160
-statistics = True
-count = True
-exclude = .*

.github/workflows/build.yml

@@ -0,0 +1,119 @@
+name: build
+
+on:
+  pull_request:
+    branches: [ master ]
+  release:
+    types: [edited, published]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: PyInstaller for ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # set to false for debugging
+      fail-fast: true
+      matrix:
+        include:
+          - os: ubuntu-20.04
+            # use old linux so that the shared library versioning is more portable
+            artifact_name: capa
+            asset_name: linux
+          - os: windows-2019
+            artifact_name: capa.exe
+            asset_name: windows
+          - os: macos-11
+            # use older macOS for assumed better portability
+            artifact_name: capa
+            asset_name: macos
+    steps:
+      - name: Checkout capa
+        uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+        with:
+          submodules: true
+      # using Python 3.8 to support running across multiple operating systems including Windows 7
+      - name: Set up Python 3.8
+        uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+        with:
+          python-version: 3.8
+      - if: matrix.os == 'ubuntu-20.04'
+        run: sudo apt-get install -y libyaml-dev
+      - name: Upgrade pip, setuptools
+        run: python -m pip install --upgrade pip setuptools
+      - name: Install capa with build requirements
+        run: pip install -e .[build]
+      - name: Cache the rule set
+        run: python ./scripts/cache-ruleset.py ./rules/ ./cache/
+      - name: Build standalone executable
+        run: pyinstaller --log-level DEBUG .github/pyinstaller/pyinstaller.spec
+      - name: Does it run (PE)?
+        run: dist/capa "tests/data/Practical Malware Analysis Lab 01-01.dll_"
+      - name: Does it run (Shellcode)?
+        run: dist/capa "tests/data/499c2a85f6e8142c3f48d4251c9c7cd6.raw32"
+      - name: Does it run (ELF)?
+        run: dist/capa "tests/data/7351f8a40c5450557b24622417fc478d.elf_"
+      - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+        with:
+          name: ${{ matrix.asset_name }}
+          path: dist/${{ matrix.artifact_name }}
+
+  test_run:
+    name: Test run on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    needs: [build]
+    strategy:
+      matrix:
+        include:
+          # OSs not already tested above
+          - os: ubuntu-22.04
+            artifact_name: capa
+            asset_name: linux
+          - os: windows-2022
+            artifact_name: capa.exe
+            asset_name: windows
+    steps:
+      - name: Download ${{ matrix.asset_name }}
+        uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2
+        with:
+          name: ${{ matrix.asset_name }}
+      - name: Set executable flag
+        if: matrix.os != 'windows-2022'
+        run: chmod +x ${{ matrix.artifact_name }}
+      - name: Run capa
+        run: ./${{ matrix.artifact_name }} -h
+
+  zip_and_upload:
+    # upload zipped binaries to Release page
+    if: github.event_name == 'release'
+    name: zip and upload ${{ matrix.asset_name }}
+    runs-on: ubuntu-20.04
+    needs: [build]
+    strategy:
+      matrix:
+        include:
+          - asset_name: linux
+            artifact_name: capa
+          - asset_name: windows
+            artifact_name: capa.exe
+          - asset_name: macos
+            artifact_name: capa
+    steps:
+      - name: Download ${{ matrix.asset_name }}
+        uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2
+        with:
+          name: ${{ matrix.asset_name }}
+      - name: Set executable flag
+        run: chmod +x ${{ matrix.artifact_name }}
+      - name: Set zip name
+        run: echo "zip_name=capa-${GITHUB_REF#refs/tags/}-${{ matrix.asset_name }}.zip" >> $GITHUB_ENV
+      - name: Zip ${{ matrix.artifact_name }} into ${{ env.zip_name }}
+        run: zip ${{ env.zip_name }} ${{ matrix.artifact_name }}
+      - name: Upload ${{ env.zip_name }} to GH Release
+        uses: svenstaro/upload-release-action@2728235f7dc9ff598bd86ce3c274b74f802d2208 # v2
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN}}
+          file: ${{ env.zip_name }}
+          tag: ${{ github.ref }}

.github/workflows/changelog.yml

@@ -0,0 +1,43 @@
+name: changelog
+
+on:
+  # We need pull_request_target instead of pull_request because a write
+  # repository token is needed to add a review to a PR. DO NOT BUILD
+  # OR RUN UNTRUSTED CODE FROM PRs IN THIS ACTION
+  pull_request_target:
+    types: [opened, edited, synchronize]
+
+permissions: read-all
+
+jobs:
+  check_changelog:
+    # no need to check for dependency updates via dependabot
+    if: github.actor != 'dependabot[bot]' && github.actor != 'dependabot-preview[bot]'
+    runs-on: ubuntu-20.04
+    env:
+      NO_CHANGELOG: '[x] No CHANGELOG update needed'
+    steps:
+    - name: Get changed files
+      id: files
+      uses: Ana06/get-changed-files@e0c398b7065a8d84700c471b6afc4116d1ba4e96 # v2.2.0
+    - name: check changelog updated
+      id: changelog_updated
+      env:
+        PR_BODY: ${{ github.event.pull_request.body }}
+        FILES: ${{ steps.files.outputs.modified }}
+      run: |
+        echo $FILES | grep -qF 'CHANGELOG.md' || echo $PR_BODY | grep -qiF "$NO_CHANGELOG"
+    - name: Reject pull request if no CHANGELOG update
+      if: ${{ always() && steps.changelog_updated.outcome == 'failure' }}
+      uses: Ana06/automatic-pull-request-review@0cf4e8a17ba79344ed3fdd7fed6dd0311d08a9d4 # v0.1.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        event: REQUEST_CHANGES
+        body: "Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the `master (unreleased)` section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: `${{ env.NO_CHANGELOG }}`"
+        allow_duplicate: false
+    - name: Dismiss previous review if CHANGELOG update
+      uses: Ana06/automatic-pull-request-review@0cf4e8a17ba79344ed3fdd7fed6dd0311d08a9d4 # v0.1.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        event: DISMISS
+        body: "CHANGELOG updated or no update needed, thanks! :smile:"

.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+# use PyPI trusted publishing, as described here: 
+# https://blog.trailofbits.com/2023/05/23/trusted-publishing-a-new-benchmark-for-packaging-security/
+name: publish to pypi
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      - name: Set up Python
+        uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+        with:
+          python-version: '3.8'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[build]
+      - name: build package
+        run: |
+          python -m build
+      - name: upload package artifacts
+        uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+        with:
+          path: dist/*
+      - name: publish package
+        uses: pypa/gh-action-pypi-publish@f5622bde02b04381239da3573277701ceca8f6a0  # release/v1
+        with:
+          skip-existing: true
+          verbose: true
+          print-hash: true

.github/workflows/scorecard.yml

@@ -0,0 +1,72 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '43 4 * * 3'
+  push:
+    branches: [ "master" ]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Uncomment the permissions below if installing in a private repository.
+      # contents: read
+      # actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@99c53751e09b9529366343771cc321ec74e9bd3d # v2.0.6
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecard on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8 # v3.1.0
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@807578363a7869ca324a79039e6db9c843e0e100 # v2.1.27
+        with:
+          sarif_file: results.sarif

.github/workflows/tag.yml

@@ -0,0 +1,32 @@
+name: tag
+
+on:
+  release:
+    types: [published]
+
+permissions: read-all
+
+jobs:
+  tag:
+    name: Tag capa rules
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout capa-rules
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      with:
+        repository: mandiant/capa-rules
+        token: ${{ secrets.CAPA_TOKEN }}
+    - name: Tag capa-rules
+      run: |
+        # user information is needed to create annotated tags (with a message)
+        git config user.email 'capa-dev@mandiant.com'
+        git config user.name 'Capa Bot'
+        name=${{ github.event.release.tag_name }}
+        git tag $name -m "https://github.com/mandiant/capa/releases/$name"
+        # TODO update branch name-major=${name%%.*}
+    - name: Push tag to capa-rules
+      uses: ad-m/github-push-action@0fafdd62b84042d49ec0cb92d9cac7f7ce4ec79e # master
+      with:
+        repository: mandiant/capa-rules
+        github_token: ${{ secrets.CAPA_TOKEN }}
+        tags: true

.github/workflows/tests.yml

@@ -0,0 +1,141 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+permissions: read-all
+
+# save workspaces to speed up testing
+env:
+  CAPA_SAVE_WORKSPACE: "True"
+
+jobs:
+  changelog_format:
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout capa
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+    # The sync GH action in capa-rules relies on a single '- *$' in the CHANGELOG file
+    - name: Ensure CHANGELOG has '- *$'
+      run: |
+        number=$(grep '\- *$' CHANGELOG.md | wc -l)
+        if [ $number != 1 ]; then exit 1; fi
+
+  code_style:
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout capa
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+    # use latest available python to take advantage of best performance
+    - name: Set up Python 3.11
+      uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+      with:
+        python-version: "3.11"
+    - name: Install dependencies
+      run: pip install -e .[dev]
+    - name: Lint with ruff
+      run: pre-commit run ruff
+    - name: Lint with isort
+      run: pre-commit run isort
+    - name: Lint with black
+      run: pre-commit run black
+    - name: Lint with flake8
+      run: pre-commit run flake8
+    - name: Check types with mypy
+      run:  pre-commit run mypy
+
+  rule_linter:
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout capa with submodules
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      with:
+        submodules: recursive
+    - name: Set up Python 3.11
+      uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+      with:
+        python-version: "3.11"
+    - name: Install capa
+      run: pip install -e .[dev]
+    - name: Run rule linter
+      run: python scripts/lint.py rules/
+
+  tests:
+    name: Tests in ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    needs: [code_style, rule_linter]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-20.04, windows-2019, macos-11]
+        # across all operating systems
+        python-version: ["3.8", "3.11"]
+        include:
+          # on Ubuntu run these as well
+          - os: ubuntu-20.04
+            python-version: "3.8"
+          - os: ubuntu-20.04
+            python-version: "3.9"
+          - os: ubuntu-20.04
+            python-version: "3.10"
+    steps:
+    - name: Checkout capa with submodules
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      with:
+        submodules: recursive
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install pyyaml
+      if: matrix.os == 'ubuntu-20.04'
+      run: sudo apt-get install -y libyaml-dev
+    - name: Install capa
+      run: pip install -e .[dev]
+    - name: Run tests
+      run: pytest -v tests/
+
+  binja-tests:
+    name: Binary Ninja tests for ${{ matrix.python-version }}
+    env:
+      BN_SERIAL: ${{ secrets.BN_SERIAL }}
+    runs-on: ubuntu-20.04
+    needs: [code_style, rule_linter]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.11"]
+    steps:
+    - name: Checkout capa with submodules
+      # do only run if BN_SERIAL is available, have to do this in every step, see https://github.com/orgs/community/discussions/26726#discussioncomment-3253118
+      if: ${{ env.BN_SERIAL != 0 }}
+      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      with:
+        submodules: recursive
+    - name: Set up Python ${{ matrix.python-version }}
+      if: ${{ env.BN_SERIAL != 0 }}
+      uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install pyyaml
+      if: ${{ env.BN_SERIAL != 0 }}
+      run: sudo apt-get install -y libyaml-dev
+    - name: Install capa
+      if: ${{ env.BN_SERIAL != 0 }}
+      run: pip install -e .[dev]
+    - name: install Binary Ninja
+      if: ${{ env.BN_SERIAL != 0 }}
+      run: |
+        mkdir ./.github/binja
+        curl "https://raw.githubusercontent.com/Vector35/binaryninja-api/6812c97/scripts/download_headless.py" -o ./.github/binja/download_headless.py
+        python ./.github/binja/download_headless.py --serial ${{ env.BN_SERIAL }} --output .github/binja/BinaryNinja-headless.zip
+        unzip .github/binja/BinaryNinja-headless.zip -d .github/binja/
+        python .github/binja/binaryninja/scripts/install_api.py --install-on-root --silent
+    - name: Run tests
+      if: ${{ env.BN_SERIAL != 0 }}
+      env:
+        BN_LICENSE: ${{ secrets.BN_LICENSE }}
+      run: pytest -v tests/test_binja_features.py  # explicitly refer to the binja tests for performance. other tests run above.

.gitignore

@@ -108,8 +108,21 @@ venv.bak/
 *.viv
 *.idb
 *.i64
+.vscode
+
 !rules/lib
 
-# hooks output
-style-checker-output.log
-rule-linter-output.log
+scripts/perf/*.txt
+scripts/perf/*.svg
+scripts/perf/*.zip
+
+.direnv
+.envrc
+.DS_Store
+*/.DS_Store
+Pipfile
+Pipfile.lock
+/cache/
+.github/binja/binaryninja
+.github/binja/download_headless.py
+.github/binja/BinaryNinja-headless.zip

.gitmodules

@@ -1,6 +1,6 @@
 [submodule "rules"]
 	path = rules
-	url = git@github.com:fireeye/capa-rules.git
+	url = ../capa-rules.git
 [submodule "tests/data"]
 	path = tests/data
-	url = git@github.com:fireeye/capa-testfiles.git
+	url = ../capa-testfiles.git

.pre-commit-config.yaml

@@ -0,0 +1,111 @@
+# install the pre-commit hooks:
+#
+#    ❯ 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
+#
+# run all linters liks:
+#
+#    ❯ pre-commit run --all-files
+#    isort....................................................................Passed
+#    black....................................................................Passed
+#    ruff.....................................................................Passed
+#    flake8...................................................................Passed
+#    mypy.....................................................................Passed
+#
+# run a single linter like:
+#
+#    ❯ pre-commit run --all-files isort
+#    isort....................................................................Passed
+
+repos:
+-   repo: local
+    hooks:
+    -   id: isort
+        name: isort
+        stages: [commit, push]
+        language: system
+        entry: isort
+        args: 
+        -   "--length-sort"
+        -   "--profile"
+        -   "black"
+        -   "--line-length=120"
+        -   "--skip-glob"
+        -   "*_pb2.py"
+        -   "capa/"
+        -   "scripts/"
+        -   "tests/"
+        always_run: true
+        pass_filenames: false
+
+-   repo: local
+    hooks:
+    -   id: black
+        name: black
+        stages: [commit, push]
+        language: system
+        entry: black
+        args: 
+        -   "--line-length=120"
+        -   "--extend-exclude"
+        -   ".*_pb2.py"
+        -   "capa/"
+        -   "scripts/"
+        -   "tests/"
+        always_run: true
+        pass_filenames: false
+
+-   repo: local
+    hooks:
+    -   id: ruff
+        name: ruff
+        stages: [commit, push]
+        language: system
+        entry: ruff
+        args: 
+        -   "check"
+        -   "--config"
+        -   ".github/ruff.toml"
+        -   "capa/"
+        -   "scripts/"
+        -   "tests/"
+        always_run: true
+        pass_filenames: false
+
+-   repo: local
+    hooks:
+    -   id: flake8
+        name: flake8
+        stages: [commit, push]
+        language: system
+        entry: flake8
+        args: 
+        -   "--config"
+        -   ".github/flake8.ini"
+        -   "--extend-exclude"
+        -   "capa/render/proto/capa_pb2.py"
+        -   "capa/"
+        -   "scripts/"
+        -   "tests/"
+        always_run: true
+        pass_filenames: false
+
+-   repo: local
+    hooks:
+    -   id: mypy
+        name: mypy
+        stages: [commit, push]
+        language: system
+        entry: mypy
+        args: 
+        -   "--check-untyped-defs"
+        -   "--ignore-missing-imports"
+        -   "--config-file=.github/mypy/mypy.ini"
+        -   "capa/"
+        -   "scripts/"
+        -   "tests/"
+        always_run: true
+        pass_filenames: false

LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (C) 2023 Mandiant, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,11 +1,22 @@
-![capa](.github/logo.png)
+![capa](https://github.com/mandiant/capa/blob/master/.github/logo.png)
 
-[![Number of rules](https://img.shields.io/badge/rules-261-blue.svg)](https://github.com/fireeye/capa-rules)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flare-capa)](https://pypi.org/project/flare-capa)
+[![Last release](https://img.shields.io/github/v/release/mandiant/capa)](https://github.com/mandiant/capa/releases)
+[![Number of rules](https://img.shields.io/badge/rules-831-blue.svg)](https://github.com/mandiant/capa-rules)
+[![CI status](https://github.com/mandiant/capa/workflows/CI/badge.svg)](https://github.com/mandiant/capa/actions?query=workflow%3ACI+event%3Apush+branch%3Amaster)
+[![Downloads](https://img.shields.io/github/downloads/mandiant/capa/total)](https://github.com/mandiant/capa/releases)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE.txt)
 
 capa detects capabilities in executable files.
-You run it against a PE file or shellcode and it tells you what it thinks the program can do.
+You run it against a PE, ELF, .NET module, or shellcode file and it tells you what it thinks the program can do.
 For example, it might suggest that the file is a backdoor, is capable of installing services, or relies on HTTP to communicate.
 
+Check out:
+- the overview in our first [capa blog post](https://www.mandiant.com/resources/capa-automatically-identify-malware-capabilities)
+- the major version 2.0 updates described in our [second blog post](https://www.mandiant.com/resources/capa-2-better-stronger-faster)
+- the major version 3.0 (ELF support) described in the [third blog post](https://www.mandiant.com/resources/elfant-in-the-room-capa-v3)
+- the major version 4.0 (.NET support) described in the [fourth blog post](https://www.mandiant.com/resources/blog/capa-v4-casting-wider-net)
+
 ```
 $ capa.exe suspicious.exe
 
@@ -56,16 +67,11 @@ $ capa.exe suspicious.exe
 
 # download and usage
 
-Download stable releases of the standalone capa binaries [here](/releases). You can run the standalone binaries without installation.
+Download stable releases of the standalone capa binaries [here](https://github.com/mandiant/capa/releases). You can run the standalone binaries without installation. capa is a command line tool that should be run from the terminal.
 
-Alternatively, you can fetch a nightly build of a standalone binary from one of the following links. These are built using the latest development branch.
-- Windows 64bit: TODO
-- Linux: TODO
-- OSX: TODO
+To use capa as a library or integrate with another tool, see [doc/installation.md](https://github.com/mandiant/capa/blob/master/doc/installation.md) for further setup instructions.
 
-To use capa as a library or integrate with another tool, see [doc/installation.md](doc/installation.md) for further setup instructions.
-
-For more information about how to use capa, including running it as an IDA script/plugin see [doc/usage.md](doc/usage.md).
+For more information about how to use capa, see [doc/usage.md](https://github.com/mandiant/capa/blob/master/doc/usage.md).
 
 # example
 
@@ -82,31 +88,40 @@ This is useful for at least two reasons:
   - it shows where within the binary an experienced analyst might study with IDA Pro
 
 ```
-λ capa.exe suspicious.exe -vv
+$ capa.exe suspicious.exe -vv
 ...
 execute shell command and capture output
 namespace   c2/shell
-author      matthew.williams@fireeye.com
+author      matthew.williams@mandiant.com
 scope       function
 att&ck      Execution::Command and Scripting Interpreter::Windows Command Shell [T1059.003]
 references  https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfoa
-examples    Practical Malware Analysis Lab 14-02.exe_:0x4011C0
-function @ 0x10003A13
+function @ 0x4011C0
   and:
-    match: create a process with modified I/O handles and window @ 0x10003A13
+    match: create a process with modified I/O handles and window @ 0x4011C0
       and:
+        number: 257 = STARTF_USESTDHANDLES | STARTF_USESHOWWINDOW @ 0x4012B8
         or:
-          api: kernel32.CreateProcess @ 0x10003D6D
-        number: 0x101 @ 0x10003B03
-        or:
-          number: 0x44 @ 0x10003ADC
-        optional:
-          api: kernel32.GetStartupInfo @ 0x10003AE4
-    match: create pipe @ 0x10003A13
+          number: 68 = StartupInfo.cb (size) @ 0x401282
+        or: = API functions that accept a pointer to a STARTUPINFO structure
+          api: kernel32.CreateProcess @ 0x401343
+    match: create pipe @ 0x4011C0
       or:
-        api: kernel32.CreatePipe @ 0x10003ACB
+        api: kernel32.CreatePipe @ 0x40126F, 0x401280
+    optional:
+      match: create thread @ 0x40136A, 0x4013BA
+        or:
+          and:
+            os: windows
+            or:
+              api: kernel32.CreateThread @ 0x4013D7
+        or:
+          and:
+            os: windows
+            or:
+              api: kernel32.CreateThread @ 0x401395
     or:
-      string: cmd.exe /c  @ 0x10003AED
+      string: "cmd.exe" @ 0x4012FD
 ...
 ```
 
@@ -122,38 +137,49 @@ rule:
   meta:
     name: hash data with CRC32
     namespace: data-manipulation/checksum/crc32
-    author: moritz.raabe@fireeye.com
+    authors:
+      - moritz.raabe@mandiant.com
     scope: function
+    mbc:
+      - Data::Checksum::CRC32 [C0032.001]
     examples:
       - 2D3EDC218A90F03089CC01715A9F047F:0x403CBD
       - 7D28CB106CB54876B2A5C111724A07CD:0x402350  # RtlComputeCrc32
+      - 7EFF498DE13CC734262F87E6B3EF38AB:0x100084A6
   features:
     - or:
       - and:
         - mnemonic: shr
-        - number: 0xEDB88320
+        - or:
+          - number: 0xEDB88320
+          - bytes: 00 00 00 00 96 30 07 77 2C 61 0E EE BA 51 09 99 19 C4 6D 07 8F F4 6A 70 35 A5 63 E9 A3 95 64 9E = crc32_tab
         - number: 8
         - characteristic: nzxor
+      - and:
+        - number: 0x8320
+        - number: 0xEDB8
+        - characteristic: nzxor
       - api: RtlComputeCrc32
 ```
 
-The [github.com/fireeye/capa-rules](https://github.com/fireeye/capa-rules) repository contains hundreds of standard library rules that are distributed with capa.
+The [github.com/mandiant/capa-rules](https://github.com/mandiant/capa-rules) repository contains hundreds of standard library rules that are distributed with capa.
 Please learn to write rules and contribute new entries as you find interesting techniques in malware.
 
-If you use IDA Pro, then you use can use the [IDA Pro plugin for capa](./capa/ida/ida_capa_explorer.py).
-This script adds new user interface elements to IDA, including an interactive tree view of rule matches and their locations within the current database.
-As you select the checkboxes, the plugin will highlight the addresses associated with the features.
-We use this plugin all the time to quickly jump to interesting parts of a program.
+If you use IDA Pro, then you can use the [capa explorer](https://github.com/mandiant/capa/tree/master/capa/ida/plugin) plugin.
+capa explorer helps you identify interesting areas of a program and build new capa rules using features extracted directly from your IDA Pro database.
 
-![capa + IDA Pro integration](.github/capa-ida.jpg)
+![capa + IDA Pro integration](https://github.com/mandiant/capa/blob/master/doc/img/explorer_expanded.png)
 
 # further information
 ## capa
-- [doc/installation](doc/installation.md)
-- [doc/usage](doc/usage.md)
-- [doc/limitations](doc/limitations.md)
-- [Contributing Guide](.github/CONTRIBUTING.md)
+- [Installation](https://github.com/mandiant/capa/blob/master/doc/installation.md)
+- [Usage](https://github.com/mandiant/capa/blob/master/doc/usage.md)
+- [Limitations](https://github.com/mandiant/capa/blob/master/doc/limitations.md)
+- [Contributing Guide](https://github.com/mandiant/capa/blob/master/.github/CONTRIBUTING.md)
 
 ## capa rules
-- [capa-rules repository](https://github.com/fireeye/capa-rules)
-- [capa-rules rule format](https://github.com/fireeye/capa-rules/blob/master/doc/format.md)
+- [capa-rules repository](https://github.com/mandiant/capa-rules)
+- [capa-rules rule format](https://github.com/mandiant/capa-rules/blob/master/doc/format.md)
+
+## capa testfiles
+The [capa-testfiles repository](https://github.com/mandiant/capa-testfiles) contains the data we use to test capa's code and rules

capa/engine.py

@@ -1,167 +1,231 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-import sys
 import copy
 import collections
+from typing import TYPE_CHECKING, Set, Dict, List, Tuple, Union, Mapping, Iterable, Iterator
 
-import capa.features
+import capa.perf
+import capa.features.common
+from capa.features.common import Result, Feature
+from capa.features.address import Address
+
+if TYPE_CHECKING:
+    # circular import, otherwise
+    import capa.rules
 
 
-class Statement(object):
+# a collection of features and the locations at which they are found.
+#
+# used throughout matching as the context in which features are searched:
+# to check if a feature exists, do: `Number(0x10) in features`.
+# to collect the locations of a feature, do: `features[Number(0x10)]`
+#
+# aliased here so that the type can be documented and xref'd.
+FeatureSet = Dict[Feature, Set[Address]]
+
+
+class Statement:
     """
     superclass for structural nodes, such as and/or/not.
     this exists to provide a default impl for `__str__` and `__repr__`,
      and to declare the interface method `evaluate`
     """
 
-    def __init__(self):
-        super(Statement, self).__init__()
+    def __init__(self, description=None):
+        super().__init__()
         self.name = self.__class__.__name__
+        self.description = description
 
     def __str__(self):
-        return "%s(%s)" % (self.name.lower(), ",".join(map(str, self.get_children())))
+        name = self.name.lower()
+        children = ",".join(map(str, self.get_children()))
+        if self.description:
+            return f"{name}({children} = {self.description})"
+        else:
+            return f"{name}({children})"
 
     def __repr__(self):
         return str(self)
 
-    def evaluate(self, ctx):
+    def evaluate(self, features: FeatureSet, short_circuit=True) -> Result:
         """
         classes that inherit `Statement` must implement `evaluate`
 
         args:
-          ctx (defaultdict[Feature, set[VA]])
-
-        returns:
-          Result
+            short_circuit (bool): if true, then statements like and/or/some may short circuit.
         """
         raise NotImplementedError()
 
-    def get_children(self):
+    def get_children(self) -> Iterator[Union["Statement", Feature]]:
         if hasattr(self, "child"):
-            yield self.child
+            # this really confuses mypy because the property may not exist
+            # since its defined in the subclasses.
+            child = self.child  # type: ignore
+            assert isinstance(child, (Statement, Feature))
+            yield child
 
         if hasattr(self, "children"):
             for child in self.children:
+                assert isinstance(child, (Statement, Feature))
                 yield child
 
     def replace_child(self, existing, new):
         if hasattr(self, "child"):
-            if self.child is existing:
+            # this really confuses mypy because the property may not exist
+            # since its defined in the subclasses.
+            if self.child is existing:  # type: ignore
                 self.child = new
 
         if hasattr(self, "children"):
-            for i, child in enumerate(self.children):
+            children = self.children
+            for i, child in enumerate(children):
                 if child is existing:
-                    self.children[i] = new
-
-
-class Result(object):
-    """
-    represents the results of an evaluation of statements against features.
-
-    instances of this class should behave like a bool,
-    e.g. `assert Result(True, ...) == True`
-
-    instances track additional metadata about evaluation results.
-    they contain references to the statement node (e.g. an And statement),
-     as well as the children Result instances.
-
-    we need this so that we can render the tree of expressions and their results.
-    """
-
-    def __init__(self, success, statement, children, locations=None):
-        """
-        args:
-          success (bool)
-          statement (capa.engine.Statement or capa.features.Feature)
-          children (list[Result])
-          locations (iterable[VA])
-        """
-        super(Result, self).__init__()
-        self.success = success
-        self.statement = statement
-        self.children = children
-        self.locations = locations if locations is not None else ()
-
-    def __eq__(self, other):
-        if isinstance(other, bool):
-            return self.success == other
-        return False
-
-    def __bool__(self):
-        return self.success
-
-    def __nonzero__(self):
-        return self.success
+                    children[i] = new
 
 
 class And(Statement):
-    """match if all of the children evaluate to True."""
+    """
+    match if all of the children evaluate to True.
 
-    def __init__(self, *children):
-        super(And, self).__init__()
-        self.children = list(children)
+    the order of evaluation is dictated by the property
+    `And.children` (type: List[Statement|Feature]).
+    a query optimizer may safely manipulate the order of these children.
+    """
 
-    def evaluate(self, ctx):
-        results = [child.evaluate(ctx) for child in self.children]
-        success = all(results)
-        return Result(success, self, results)
+    def __init__(self, children, description=None):
+        super().__init__(description=description)
+        self.children = children
+
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.and"] += 1
+
+        if short_circuit:
+            results = []
+            for child in self.children:
+                result = child.evaluate(ctx, short_circuit=short_circuit)
+                results.append(result)
+                if not result:
+                    # short circuit
+                    return Result(False, self, results)
+
+            return Result(True, self, results)
+        else:
+            results = [child.evaluate(ctx, short_circuit=short_circuit) for child in self.children]
+            success = all(results)
+            return Result(success, self, results)
 
 
 class Or(Statement):
-    """match if any of the children evaluate to True."""
+    """
+    match if any of the children evaluate to True.
 
-    def __init__(self, *children):
-        super(Or, self).__init__()
-        self.children = list(children)
+    the order of evaluation is dictated by the property
+    `Or.children` (type: List[Statement|Feature]).
+    a query optimizer may safely manipulate the order of these children.
+    """
 
-    def evaluate(self, ctx):
-        results = [child.evaluate(ctx) for child in self.children]
-        success = any(results)
-        return Result(success, self, results)
+    def __init__(self, children, description=None):
+        super().__init__(description=description)
+        self.children = children
+
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.or"] += 1
+
+        if short_circuit:
+            results = []
+            for child in self.children:
+                result = child.evaluate(ctx, short_circuit=short_circuit)
+                results.append(result)
+                if result:
+                    # short circuit as soon as we hit one match
+                    return Result(True, self, results)
+
+            return Result(False, self, results)
+        else:
+            results = [child.evaluate(ctx, short_circuit=short_circuit) for child in self.children]
+            success = any(results)
+            return Result(success, self, results)
 
 
 class Not(Statement):
     """match only if the child evaluates to False."""
 
-    def __init__(self, child):
-        super(Not, self).__init__()
+    def __init__(self, child, description=None):
+        super().__init__(description=description)
         self.child = child
 
-    def evaluate(self, ctx):
-        results = [self.child.evaluate(ctx)]
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.not"] += 1
+
+        results = [self.child.evaluate(ctx, short_circuit=short_circuit)]
         success = not results[0]
         return Result(success, self, results)
 
 
 class Some(Statement):
-    """match if at least N of the children evaluate to True."""
+    """
+    match if at least N of the children evaluate to True.
 
-    def __init__(self, count, *children):
-        super(Some, self).__init__()
+    the order of evaluation is dictated by the property
+    `Some.children` (type: List[Statement|Feature]).
+    a query optimizer may safely manipulate the order of these children.
+    """
+
+    def __init__(self, count, children, description=None):
+        super().__init__(description=description)
         self.count = count
-        self.children = list(children)
+        self.children = children
 
-    def evaluate(self, ctx):
-        results = [child.evaluate(ctx) for child in self.children]
-        # note that here we cast the child result as a bool
-        # because we've overridden `__bool__` above.
-        #
-        # we can't use `if child is True` because the instance is not True.
-        success = sum([1 for child in results if bool(child) is True]) >= self.count
-        return Result(success, self, results)
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.some"] += 1
+
+        if short_circuit:
+            results = []
+            satisfied_children_count = 0
+            for child in self.children:
+                result = child.evaluate(ctx, short_circuit=short_circuit)
+                results.append(result)
+                if result:
+                    satisfied_children_count += 1
+
+                if satisfied_children_count >= self.count:
+                    # short circuit as soon as we hit the threshold
+                    return Result(True, self, results)
+
+            return Result(False, self, results)
+        else:
+            results = [child.evaluate(ctx, short_circuit=short_circuit) for child in self.children]
+            # note that here we cast the child result as a bool
+            # because we've overridden `__bool__` above.
+            #
+            # we can't use `if child is True` because the instance is not True.
+            success = sum([1 for child in results if bool(child) is True]) >= self.count
+            return Result(success, self, results)
 
 
 class Range(Statement):
     """match if the child is contained in the ctx set with a count in the given range."""
 
-    def __init__(self, child, min=None, max=None):
-        super(Range, self).__init__()
+    def __init__(self, child, min=None, max=None, description=None):
+        super().__init__(description=description)
         self.child = child
         self.min = min if min is not None else 0
         self.max = max if max is not None else (1 << 64 - 1)
 
-    def evaluate(self, ctx):
+    def evaluate(self, ctx, **kwargs):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.range"] += 1
+
         count = len(ctx.get(self.child, []))
         if self.min == 0 and count == 0:
             return Result(True, self, [])
@@ -170,9 +234,9 @@ class Range(Statement):
 
     def __str__(self):
         if self.max == (1 << 64 - 1):
-            return "range(%s, min=%d, max=infinity)" % (str(self.child), self.min)
+            return f"range({str(self.child)}, min={self.min}, max=infinity)"
         else:
-            return "range(%s, min=%d, max=%d)" % (str(self.child), self.min, self.max)
+            return f"range({str(self.child)}, min={self.min}, max={self.max})"
 
 
 class Subscope(Statement):
@@ -181,59 +245,66 @@ class Subscope(Statement):
     the engine should preprocess rules to extract subscope statements into their own rules.
     """
 
-    def __init__(self, scope, child):
-        super(Subscope, self).__init__()
+    def __init__(self, scope, child, description=None):
+        super().__init__(description=description)
         self.scope = scope
         self.child = child
 
-    def evaluate(self, ctx):
+    def evaluate(self, ctx, **kwargs):
         raise ValueError("cannot evaluate a subscope directly!")
 
 
-def topologically_order_rules(rules):
+# mapping from rule name to list of: (location of match, result object)
+#
+# used throughout matching and rendering to collection the results
+#  of statement evaluation and their locations.
+#
+# to check if a rule matched, do: `"TCP client" in matches`.
+# to find where a rule matched, do: `map(first, matches["TCP client"])`
+# to see how a rule matched, do:
+#
+#     for address, match_details in matches["TCP client"]:
+#         inspect(match_details)
+#
+# aliased here so that the type can be documented and xref'd.
+MatchResults = Mapping[str, List[Tuple[Address, Result]]]
+
+
+def index_rule_matches(features: FeatureSet, rule: "capa.rules.Rule", locations: Iterable[Address]):
     """
-    order the given rules such that dependencies show up before dependents.
-    this means that as we match rules, we can add features for the matches, and these
-     will be matched by subsequent rules if they follow this order.
+    record into the given featureset that the given rule matched at the given locations.
 
-    assumes that the rule dependency graph is a DAG.
+    naively, this is just adding a MatchedRule feature;
+    however, we also want to record matches for the rule's namespaces.
+
+    updates `features` in-place. doesn't modify the remaining arguments.
     """
-    # we evaluate `rules` multiple times, so if its a generator, realize it into a list.
-    rules = list(rules)
-    namespaces = capa.rules.index_rules_by_namespace(rules)
-    rules = {rule.name: rule for rule in rules}
-    seen = set([])
-    ret = []
-
-    def rec(rule):
-        if rule.name in seen:
-            return
-
-        for dep in rule.get_dependencies(namespaces):
-            rec(rules[dep])
-
-        ret.append(rule)
-        seen.add(rule.name)
-
-    for rule in rules.values():
-        rec(rule)
-
-    return ret
+    features[capa.features.common.MatchedRule(rule.name)].update(locations)
+    namespace = rule.meta.get("namespace")
+    if namespace:
+        while namespace:
+            features[capa.features.common.MatchedRule(namespace)].update(locations)
+            namespace, _, _ = namespace.rpartition("/")
 
 
-def match(rules, features, va):
+def match(rules: List["capa.rules.Rule"], features: FeatureSet, addr: Address) -> Tuple[FeatureSet, MatchResults]:
     """
-    Args:
-      rules (List[capa.rules.Rule]): these must already be ordered topologically by dependency.
-      features (Mapping[capa.features.Feature, int]):
-      va (int): location of the features
+    match the given rules against the given features,
+    returning an updated set of features and the matches.
 
-    Returns:
-      Tuple[List[capa.features.Feature], Dict[str, Tuple[int, capa.engine.Result]]]: two-tuple with entries:
-        - list of features used for matching (which may be greater than argument, due to rule match features), and
-        - mapping from rule name to (location of match, result object)
+    the updated features are just like the input,
+    but extended to include the match features (e.g. names of rules that matched).
+    the given feature set is not modified; an updated copy is returned.
+
+    the given list of rules must be ordered topologically by dependency,
+    or else `match` statements will not be handled correctly.
+
+    this routine should be fairly optimized, but is not guaranteed to be the fastest matcher possible.
+    it has a particularly convenient signature: (rules, features) -> matches
+    other strategies can be imagined that match differently; implement these elsewhere.
+    specifically, this routine does "top down" matching of the given rules against the feature set.
     """
-    results = collections.defaultdict(list)
+    results = collections.defaultdict(list)  # type: MatchResults
 
     # copy features so that we can modify it
     # without affecting the caller (keep this function pure)
@@ -242,15 +313,22 @@ def match(rules, features, va):
     features = collections.defaultdict(set, copy.copy(features))
 
     for rule in rules:
-        res = rule.evaluate(features)
+        res = rule.evaluate(features, short_circuit=True)
         if res:
-            results[rule.name].append((va, res))
-            features[capa.features.MatchedRule(rule.name)].add(va)
+            # we first matched the rule with short circuiting enabled.
+            # this is much faster than without short circuiting.
+            # however, we want to collect all results thoroughly,
+            # so once we've found a match quickly,
+            # go back and capture results without short circuiting.
+            res = rule.evaluate(features, short_circuit=False)
 
-            namespace = rule.meta.get("namespace")
-            if namespace:
-                while namespace:
-                    features[capa.features.MatchedRule(namespace)].add(va)
-                    namespace, _, _ = namespace.rpartition("/")
+            # sanity check
+            assert bool(res) is True
+
+            results[rule.name].append((addr, res))
+            # we need to update the current `features`
+            # because subsequent iterations of this loop may use newly added features,
+            # such as rule or namespace matches.
+            index_rule_matches(features, rule, [addr])
 
     return (features, results)

capa/exceptions.py

@@ -0,0 +1,21 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+class UnsupportedRuntimeError(RuntimeError):
+    pass
+
+
+class UnsupportedFormatError(ValueError):
+    pass
+
+
+class UnsupportedArchError(ValueError):
+    pass
+
+
+class UnsupportedOSError(ValueError):
+    pass

capa/features/__init__.py

@@ -1,152 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import re
-import sys
-import codecs
-import logging
-
-import capa.engine
-
-logger = logging.getLogger(__name__)
-MAX_BYTES_FEATURE_SIZE = 0x100
-
-
-def bytes_to_str(b):
-    if sys.version_info[0] >= 3:
-        return str(codecs.encode(b, "hex").decode("utf-8"))
-    else:
-        return codecs.encode(b, "hex")
-
-
-def hex_string(h):
-    """ render hex string e.g. "0a40b1" as "0A 40 B1" """
-    return " ".join(h[i : i + 2] for i in range(0, len(h), 2)).upper()
-
-
-class Feature(object):
-    def __init__(self, value, description=None):
-        super(Feature, self).__init__()
-        self.name = self.__class__.__name__.lower()
-        self.value = value
-        self.description = description
-
-    def __hash__(self):
-        return hash((self.name, self.value))
-
-    def __eq__(self, other):
-        return self.name == other.name and self.value == other.value
-
-    # Used to overwrite the rendering of the feature value in `__str__` and the
-    # json output
-    def get_value_str(self):
-        return self.value
-
-    def __str__(self):
-        if self.value:
-            if self.description:
-                return "%s(%s = %s)" % (self.name, self.get_value_str(), self.description)
-            else:
-                return "%s(%s)" % (self.name, self.get_value_str())
-        else:
-            return "%s" % self.name
-
-    def __repr__(self):
-        return str(self)
-
-    def evaluate(self, ctx):
-        return capa.engine.Result(self in ctx, self, [], locations=ctx.get(self, []))
-
-    def serialize(self):
-        return self.__dict__
-
-    def freeze_serialize(self):
-        return (self.__class__.__name__, [self.value])
-
-    @classmethod
-    def freeze_deserialize(cls, args):
-        return cls(*args)
-
-
-class MatchedRule(Feature):
-    def __init__(self, value, description=None):
-        super(MatchedRule, self).__init__(value, description)
-        self.name = "match"
-
-
-class Characteristic(Feature):
-    def __init__(self, value, description=None):
-        super(Characteristic, self).__init__(value, description)
-
-
-class String(Feature):
-    def __init__(self, value, description=None):
-        super(String, self).__init__(value, description)
-
-
-class Regex(String):
-    def __init__(self, value, description=None):
-        super(Regex, self).__init__(value, description)
-        pat = self.value[len("/") : -len("/")]
-        flags = re.DOTALL
-        if value.endswith("/i"):
-            pat = self.value[len("/") : -len("/i")]
-            flags |= re.IGNORECASE
-        try:
-            self.re = re.compile(pat, flags)
-        except re.error:
-            if value.endswith("/i"):
-                value = value[: -len("i")]
-            raise ValueError(
-                "invalid regular expression: %s it should use Python syntax, try it at https://pythex.org" % value
-            )
-        self.match = None
-
-    def evaluate(self, ctx):
-        for feature, locations in ctx.items():
-            if not isinstance(feature, (capa.features.String,)):
-                continue
-
-            # `re.search` finds a match anywhere in the given string
-            # which implies leading and/or trailing whitespace.
-            # using this mode cleans is more convenient for rule authors,
-            # so that they don't have to prefix/suffix their terms like: /.*foo.*/.
-            if self.re.search(feature.value):
-                self.match = feature.value
-                return capa.engine.Result(True, self, [], locations=locations)
-
-        return capa.engine.Result(False, self, [])
-
-    def __str__(self):
-        return 'regex(string =~ %s, matched = "%s")' % (self.value, self.match)
-
-
-class StringFactory(object):
-    def __new__(self, value, description):
-        if value.startswith("/") and (value.endswith("/") or value.endswith("/i")):
-            return Regex(value, description)
-        return String(value, description)
-
-
-class Bytes(Feature):
-    def __init__(self, value, description=None):
-        super(Bytes, self).__init__(value, description)
-
-    def evaluate(self, ctx):
-        for feature, locations in ctx.items():
-            if not isinstance(feature, (capa.features.Bytes,)):
-                continue
-
-            if feature.value.startswith(self.value):
-                return capa.engine.Result(True, self, [], locations=locations)
-
-        return capa.engine.Result(False, self, [])
-
-    def get_value_str(self):
-        return hex_string(bytes_to_str(self.value))
-
-    def freeze_serialize(self):
-        return (self.__class__.__name__, [bytes_to_str(self.value).upper()])
-
-    @classmethod
-    def freeze_deserialize(cls, args):
-        return cls(*[codecs.decode(x, "hex") for x in args])

capa/features/address.py

@@ -0,0 +1,121 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import abc
+
+
+class Address(abc.ABC):
+    @abc.abstractmethod
+    def __eq__(self, other):
+        ...
+
+    @abc.abstractmethod
+    def __lt__(self, other):
+        # implement < so that addresses can be sorted from low to high
+        ...
+
+    @abc.abstractmethod
+    def __hash__(self):
+        # implement hash so that addresses can be used in sets and dicts
+        ...
+
+    @abc.abstractmethod
+    def __repr__(self):
+        # implement repr to help during debugging
+        ...
+
+
+class AbsoluteVirtualAddress(int, Address):
+    """an absolute memory address"""
+
+    def __new__(cls, v):
+        assert v >= 0
+        return int.__new__(cls, v)
+
+    def __repr__(self):
+        return f"absolute(0x{self:x})"
+
+    def __hash__(self):
+        return int.__hash__(self)
+
+
+class RelativeVirtualAddress(int, Address):
+    """a memory address relative to a base address"""
+
+    def __repr__(self):
+        return f"relative(0x{self:x})"
+
+    def __hash__(self):
+        return int.__hash__(self)
+
+
+class FileOffsetAddress(int, Address):
+    """an address relative to the start of a file"""
+
+    def __new__(cls, v):
+        assert v >= 0
+        return int.__new__(cls, v)
+
+    def __repr__(self):
+        return f"file(0x{self:x})"
+
+    def __hash__(self):
+        return int.__hash__(self)
+
+
+class DNTokenAddress(int, Address):
+    """a .NET token"""
+
+    def __new__(cls, token: int):
+        return int.__new__(cls, token)
+
+    def __repr__(self):
+        return f"token(0x{self:x})"
+
+    def __hash__(self):
+        return int.__hash__(self)
+
+
+class DNTokenOffsetAddress(Address):
+    """an offset into an object specified by a .NET token"""
+
+    def __init__(self, token: int, offset: int):
+        assert offset >= 0
+        self.token = token
+        self.offset = offset
+
+    def __eq__(self, other):
+        return (self.token, self.offset) == (other.token, other.offset)
+
+    def __lt__(self, other):
+        return (self.token, self.offset) < (other.token, other.offset)
+
+    def __hash__(self):
+        return hash((self.token, self.offset))
+
+    def __repr__(self):
+        return f"token(0x{self.token:x})+(0x{self.offset:x})"
+
+    def __index__(self):
+        return self.token + self.offset
+
+
+class _NoAddress(Address):
+    def __eq__(self, other):
+        return True
+
+    def __lt__(self, other):
+        return False
+
+    def __hash__(self):
+        return hash(0)
+
+    def __repr__(self):
+        return "no address"
+
+
+NO_ADDRESS = _NoAddress()

capa/features/basicblock.py

@@ -1,21 +1,20 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-from capa.features import Feature
+from capa.features.common import Feature
 
 
 class BasicBlock(Feature):
-    def __init__(self):
-        super(BasicBlock, self).__init__(None)
+    def __init__(self, description=None):
+        super().__init__(0, description=description)
 
     def __str__(self):
         return "basic block"
 
     def get_value_str(self):
         return ""
-
-    def freeze_serialize(self):
-        return (self.__class__.__name__, [])
-
-    @classmethod
-    def freeze_deserialize(cls, args):
-        return cls()

capa/features/common.py

@@ -0,0 +1,476 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import re
+import abc
+import codecs
+import typing
+import logging
+import collections
+from typing import TYPE_CHECKING, Set, Dict, List, Union, Optional
+
+if TYPE_CHECKING:
+    # circular import, otherwise
+    import capa.engine
+
+import capa.perf
+import capa.features
+import capa.features.extractors.elf
+from capa.features.address import Address
+
+logger = logging.getLogger(__name__)
+MAX_BYTES_FEATURE_SIZE = 0x100
+
+# thunks may be chained so we specify a delta to control the depth to which these chains are explored
+THUNK_CHAIN_DEPTH_DELTA = 5
+
+
+class FeatureAccess:
+    READ = "read"
+    WRITE = "write"
+
+
+VALID_FEATURE_ACCESS = (FeatureAccess.READ, FeatureAccess.WRITE)
+
+
+def bytes_to_str(b: bytes) -> str:
+    return str(codecs.encode(b, "hex").decode("utf-8"))
+
+
+def hex_string(h: str) -> str:
+    """render hex string e.g. "0a40b1" as "0A 40 B1" """
+    return " ".join(h[i : i + 2] for i in range(0, len(h), 2)).upper()
+
+
+def escape_string(s: str) -> str:
+    """escape special characters"""
+    s = repr(s)
+    if not s.startswith(('"', "'")):
+        # u'hello\r\nworld' -> hello\\r\\nworld
+        s = s[2:-1]
+    else:
+        # 'hello\r\nworld' -> hello\\r\\nworld
+        s = s[1:-1]
+    s = s.replace("\\'", "'")  # repr() may escape "'" in some edge cases, remove
+    s = s.replace('"', '\\"')  # repr() does not escape '"', add
+    return s
+
+
+class Result:
+    """
+    represents the results of an evaluation of statements against features.
+
+    instances of this class should behave like a bool,
+    e.g. `assert Result(True, ...) == True`
+
+    instances track additional metadata about evaluation results.
+    they contain references to the statement node (e.g. an And statement),
+     as well as the children Result instances.
+
+    we need this so that we can render the tree of expressions and their results.
+    """
+
+    def __init__(
+        self,
+        success: bool,
+        statement: Union["capa.engine.Statement", "Feature"],
+        children: List["Result"],
+        locations: Optional[Set[Address]] = None,
+    ):
+        super().__init__()
+        self.success = success
+        self.statement = statement
+        self.children = children
+        self.locations = locations if locations is not None else set()
+
+    def __eq__(self, other):
+        if isinstance(other, bool):
+            return self.success == other
+        return False
+
+    def __bool__(self):
+        return self.success
+
+    def __nonzero__(self):
+        return self.success
+
+
+class Feature(abc.ABC):  # noqa: B024
+    # this is an abstract class, since we don't want anyone to instantiate it directly,
+    # but it doesn't have any abstract methods.
+
+    def __init__(
+        self,
+        value: Union[str, int, float, bytes],
+        description: Optional[str] = None,
+    ):
+        """
+        Args:
+          value (any): the value of the feature, such as the number or string.
+          description (str): a human-readable description that explains the feature value.
+        """
+        super().__init__()
+
+        self.name = self.__class__.__name__.lower()
+        self.value = value
+        self.description = description
+
+    def __hash__(self):
+        return hash((self.name, self.value))
+
+    def __eq__(self, other):
+        return self.name == other.name and self.value == other.value
+
+    def __lt__(self, other):
+        # implementing sorting by serializing to JSON is a huge hack.
+        # its slow, inelegant, and probably doesn't work intuitively;
+        # however, we only use it for deterministic output, so it's good enough for now.
+
+        # circular import
+        # we should fix if this wasn't already a huge hack.
+        import capa.features.freeze.features
+
+        return (
+            capa.features.freeze.features.feature_from_capa(self).model_dump_json()
+            < capa.features.freeze.features.feature_from_capa(other).model_dump_json()
+        )
+
+    def get_name_str(self) -> str:
+        """
+        render the name of this feature, for use by `__str__` and friends.
+        subclasses should override to customize the rendering.
+        """
+        return self.name
+
+    def get_value_str(self) -> str:
+        """
+        render the value of this feature, for use by `__str__` and friends.
+        subclasses should override to customize the rendering.
+        """
+        return str(self.value)
+
+    def __str__(self):
+        if self.value is not None:
+            if self.description:
+                return f"{self.get_name_str()}({self.get_value_str()} = {self.description})"
+            else:
+                return f"{self.get_name_str()}({self.get_value_str()})"
+        else:
+            return f"{self.get_name_str()}"
+
+    def __repr__(self):
+        return str(self)
+
+    def evaluate(self, ctx: Dict["Feature", Set[Address]], **kwargs) -> Result:
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature." + self.name] += 1
+        return Result(self in ctx, self, [], locations=ctx.get(self, set()))
+
+
+class MatchedRule(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.name = "match"
+
+
+class Characteristic(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+
+
+class String(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+
+    def get_value_str(self) -> str:
+        assert isinstance(self.value, str)
+        return escape_string(self.value)
+
+
+class Class(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+
+
+class Namespace(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+
+
+class Substring(String):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.value = value
+
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.substring"] += 1
+
+        # mapping from string value to list of locations.
+        # will unique the locations later on.
+        matches: typing.DefaultDict[str, Set[Address]] = collections.defaultdict(set)
+
+        assert isinstance(self.value, str)
+        for feature, locations in ctx.items():
+            if not isinstance(feature, (String,)):
+                continue
+
+            if not isinstance(feature.value, str):
+                # this is a programming error: String should only contain str
+                raise ValueError("unexpected feature value type")
+
+            if self.value in feature.value:
+                matches[feature.value].update(locations)
+                if short_circuit:
+                    # we found one matching string, thats sufficient to match.
+                    # don't collect other matching strings in this mode.
+                    break
+
+        if matches:
+            # collect all locations
+            locations = set()
+            for locs in matches.values():
+                locations.update(locs)
+
+            # unlike other features, we cannot return put a reference to `self` directly in a `Result`.
+            # this is because `self` may match on many strings, so we can't stuff the matched value into it.
+            # instead, return a new instance that has a reference to both the substring and the matched values.
+            return Result(True, _MatchedSubstring(self, dict(matches)), [], locations=locations)
+        else:
+            return Result(False, _MatchedSubstring(self, {}), [])
+
+    def get_value_str(self) -> str:
+        assert isinstance(self.value, str)
+        return escape_string(self.value)
+
+    def __str__(self):
+        assert isinstance(self.value, str)
+        return f"substring({escape_string(self.value)})"
+
+
+class _MatchedSubstring(Substring):
+    """
+    this represents specific match instances of a substring feature.
+    treat it the same as a `Substring` except it has the `matches` field that contains the complete strings that matched.
+
+    note: this type should only ever be constructed by `Substring.evaluate()`. it is not part of the public API.
+    """
+
+    def __init__(self, substring: Substring, matches: Dict[str, Set[Address]]):
+        """
+        args:
+          substring: the substring feature that matches.
+          match: mapping from matching string to its locations.
+        """
+        super().__init__(str(substring.value), description=substring.description)
+        # we want this to collide with the name of `Substring` above,
+        # so that it works nicely with the renderers.
+        self.name = "substring"
+        # this may be None if the substring doesn't match
+        self.matches = matches
+
+    def __str__(self):
+        matches = ", ".join(f'"{s}"' for s in (self.matches or {}).keys())
+        assert isinstance(self.value, str)
+        return f'substring("{self.value}", matches = {matches})'
+
+
+class Regex(String):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.value = value
+
+        pat = self.value[len("/") : -len("/")]
+        flags = re.DOTALL
+        if value.endswith("/i"):
+            pat = self.value[len("/") : -len("/i")]
+            flags |= re.IGNORECASE
+        try:
+            self.re = re.compile(pat, flags)
+        except re.error as exc:
+            if value.endswith("/i"):
+                value = value[: -len("i")]
+            raise ValueError(
+                f"invalid regular expression: {value} it should use Python syntax, try it at https://pythex.org"
+            ) from exc
+
+    def evaluate(self, ctx, short_circuit=True):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.regex"] += 1
+
+        # mapping from string value to list of locations.
+        # will unique the locations later on.
+        matches: typing.DefaultDict[str, Set[Address]] = collections.defaultdict(set)
+
+        for feature, locations in ctx.items():
+            if not isinstance(feature, (String,)):
+                continue
+
+            if not isinstance(feature.value, str):
+                # this is a programming error: String should only contain str
+                raise ValueError("unexpected feature value type")
+
+            # `re.search` finds a match anywhere in the given string
+            # which implies leading and/or trailing whitespace.
+            # using this mode cleans is more convenient for rule authors,
+            # so that they don't have to prefix/suffix their terms like: /.*foo.*/.
+            if self.re.search(feature.value):
+                matches[feature.value].update(locations)
+                if short_circuit:
+                    # we found one matching string, thats sufficient to match.
+                    # don't collect other matching strings in this mode.
+                    break
+
+        if matches:
+            # collect all locations
+            locations = set()
+            for locs in matches.values():
+                locations.update(locs)
+
+            # unlike other features, we cannot return put a reference to `self` directly in a `Result`.
+            # this is because `self` may match on many strings, so we can't stuff the matched value into it.
+            # instead, return a new instance that has a reference to both the regex and the matched values.
+            # see #262.
+            return Result(True, _MatchedRegex(self, dict(matches)), [], locations=locations)
+        else:
+            return Result(False, _MatchedRegex(self, {}), [])
+
+    def __str__(self):
+        assert isinstance(self.value, str)
+        return f"regex(string =~ {self.value})"
+
+
+class _MatchedRegex(Regex):
+    """
+    this represents specific match instances of a regular expression feature.
+    treat it the same as a `Regex` except it has the `matches` field that contains the complete strings that matched.
+
+    note: this type should only ever be constructed by `Regex.evaluate()`. it is not part of the public API.
+    """
+
+    def __init__(self, regex: Regex, matches: Dict[str, Set[Address]]):
+        """
+        args:
+          regex: the regex feature that matches.
+          matches: mapping from matching string to its locations.
+        """
+        super().__init__(str(regex.value), description=regex.description)
+        # we want this to collide with the name of `Regex` above,
+        # so that it works nicely with the renderers.
+        self.name = "regex"
+        # this may be None if the regex doesn't match
+        self.matches = matches
+
+    def __str__(self):
+        matches = ", ".join(f'"{s}"' for s in (self.matches or {}).keys())
+        assert isinstance(self.value, str)
+        return f"regex(string =~ {self.value}, matches = {matches})"
+
+
+class StringFactory:
+    def __new__(cls, value: str, description=None):
+        if value.startswith("/") and (value.endswith("/") or value.endswith("/i")):
+            return Regex(value, description=description)
+        return String(value, description=description)
+
+
+class Bytes(Feature):
+    def __init__(self, value: bytes, description=None):
+        super().__init__(value, description=description)
+        self.value = value
+
+    def evaluate(self, ctx, **kwargs):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature.bytes"] += 1
+
+        assert isinstance(self.value, bytes)
+        for feature, locations in ctx.items():
+            if not isinstance(feature, (Bytes,)):
+                continue
+
+            assert isinstance(feature.value, bytes)
+            if feature.value.startswith(self.value):
+                return Result(True, self, [], locations=locations)
+
+        return Result(False, self, [])
+
+    def get_value_str(self):
+        assert isinstance(self.value, bytes)
+        return hex_string(bytes_to_str(self.value))
+
+
+# other candidates here: https://docs.microsoft.com/en-us/windows/win32/debug/pe-format#machine-types
+ARCH_I386 = "i386"
+ARCH_AMD64 = "amd64"
+# dotnet
+ARCH_ANY = "any"
+VALID_ARCH = (ARCH_I386, ARCH_AMD64, ARCH_ANY)
+
+
+class Arch(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.name = "arch"
+
+
+OS_WINDOWS = "windows"
+OS_LINUX = "linux"
+OS_MACOS = "macos"
+# dotnet
+OS_ANY = "any"
+VALID_OS = {os.value for os in capa.features.extractors.elf.OS}
+VALID_OS.update({OS_WINDOWS, OS_LINUX, OS_MACOS, OS_ANY})
+# internal only, not to be used in rules
+OS_AUTO = "auto"
+
+
+class OS(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.name = "os"
+
+    def evaluate(self, ctx, **kwargs):
+        capa.perf.counters["evaluate.feature"] += 1
+        capa.perf.counters["evaluate.feature." + self.name] += 1
+
+        for feature, locations in ctx.items():
+            if not isinstance(feature, (OS,)):
+                continue
+
+            assert isinstance(feature.value, str)
+            if OS_ANY in (self.value, feature.value) or self.value == feature.value:
+                return Result(True, self, [], locations=locations)
+
+        return Result(False, self, [])
+
+
+FORMAT_PE = "pe"
+FORMAT_ELF = "elf"
+FORMAT_DOTNET = "dotnet"
+VALID_FORMAT = (FORMAT_PE, FORMAT_ELF, FORMAT_DOTNET)
+# internal only, not to be used in rules
+FORMAT_AUTO = "auto"
+FORMAT_SC32 = "sc32"
+FORMAT_SC64 = "sc64"
+FORMAT_FREEZE = "freeze"
+FORMAT_RESULT = "result"
+FORMAT_UNKNOWN = "unknown"
+
+
+class Format(Feature):
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+        self.name = "format"
+
+
+def is_global_feature(feature):
+    """
+    is this a feature that is extracted at every scope?
+    today, these are OS and arch features.
+    """
+    return isinstance(feature, (OS, Arch))

capa/features/extractors/__init__.py

@@ -1,280 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import abc
-
-
-class FeatureExtractor(object):
-    """
-    FeatureExtractor defines the interface for fetching features from a sample.
-
-    There may be multiple backends that support fetching features for capa.
-    For example, we use vivisect by default, but also want to support saving
-     and restoring features from a JSON file.
-    When we restore the features, we'd like to use exactly the same matching logic
-     to find matching rules.
-    Therefore, we can define a FeatureExtractor that provides features from the
-     serialized JSON file and do matching without a binary analysis pass.
-    Also, this provides a way to hook in an IDA backend.
-
-    This class is not instantiated directly; it is the base class for other implementations.
-    """
-
-    __metaclass__ = abc.ABCMeta
-
-    def __init__(self):
-        #
-        # note: a subclass should define ctor parameters for its own use.
-        #  for example, the Vivisect feature extract might require the vw and/or path.
-        # this base class doesn't know what to do with that info, though.
-        #
-        super(FeatureExtractor, self).__init__()
-
-    @abc.abstractmethod
-    def get_base_address(self):
-        """
-        fetch the preferred load address at which the sample was analyzed.
-
-        returns: int
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def extract_file_features(self):
-        """
-        extract file-scope features.
-
-        example::
-
-            extractor = VivisectFeatureExtractor(vw, path)
-            for feature, va in extractor.get_file_features():
-                print('0x%x: %s', va, feature)
-
-        yields:
-          Tuple[capa.features.Feature, int]: feature and its location
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def get_functions(self):
-        """
-        enumerate the functions and provide opaque values that will
-         subsequently be provided to `.extract_function_features()`, etc.
-
-        by "opaque value", we mean that this can be any object, as long as it
-         provides enough context to `.extract_function_features()`.
-
-        the opaque value should support casting to int (`__int__`) for the function start address.
-
-        yields:
-          any: the opaque function value.
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def extract_function_features(self, f):
-        """
-        extract function-scope features.
-        the arguments are opaque values previously provided by `.get_functions()`, etc.
-
-        example::
-
-            extractor = VivisectFeatureExtractor(vw, path)
-            for function in extractor.get_functions():
-                for feature, va in extractor.extract_function_features(function):
-                    print('0x%x: %s', va, feature)
-
-        args:
-          f [any]: an opaque value previously fetched from `.get_functions()`.
-
-        yields:
-          Tuple[capa.features.Feature, int]: feature and its location
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def get_basic_blocks(self, f):
-        """
-        enumerate the basic blocks in the given function and provide opaque values that will
-         subsequently be provided to `.extract_basic_block_features()`, etc.
-
-        by "opaque value", we mean that this can be any object, as long as it
-         provides enough context to `.extract_basic_block_features()`.
-
-        the opaque value should support casting to int (`__int__`) for the basic block start address.
-
-        yields:
-          any: the opaque basic block value.
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def extract_basic_block_features(self, f, bb):
-        """
-        extract basic block-scope features.
-        the arguments are opaque values previously provided by `.get_functions()`, etc.
-
-        example::
-
-            extractor = VivisectFeatureExtractor(vw, path)
-            for function in extractor.get_functions():
-                for bb in extractor.get_basic_blocks(function):
-                    for feature, va in extractor.extract_basic_block_features(function, bb):
-                        print('0x%x: %s', va, feature)
-
-        args:
-          f [any]: an opaque value previously fetched from `.get_functions()`.
-          bb [any]: an opaque value previously fetched from `.get_basic_blocks()`.
-
-        yields:
-          Tuple[capa.features.Feature, int]: feature and its location
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def get_instructions(self, f, bb):
-        """
-        enumerate the instructions in the given basic block and provide opaque values that will
-         subsequently be provided to `.extract_insn_features()`, etc.
-
-        by "opaque value", we mean that this can be any object, as long as it
-         provides enough context to `.extract_insn_features()`.
-
-        the opaque value should support casting to int (`__int__`) for the instruction address.
-
-        yields:
-          any: the opaque function value.
-        """
-        raise NotImplemented
-
-    @abc.abstractmethod
-    def extract_insn_features(self, f, bb, insn):
-        """
-        extract instruction-scope features.
-        the arguments are opaque values previously provided by `.get_functions()`, etc.
-
-        example::
-
-            extractor = VivisectFeatureExtractor(vw, path)
-            for function in extractor.get_functions():
-                for bb in extractor.get_basic_blocks(function):
-                    for insn in extractor.get_instructions(function, bb):
-                        for feature, va in extractor.extract_insn_features(function, bb, insn):
-                            print('0x%x: %s', va, feature)
-
-        args:
-          f [any]: an opaque value previously fetched from `.get_functions()`.
-          bb [any]: an opaque value previously fetched from `.get_basic_blocks()`.
-          insn [any]: an opaque value previously fetched from `.get_instructions()`.
-
-        yields:
-          Tuple[capa.features.Feature, int]: feature and its location
-        """
-        raise NotImplemented
-
-
-class NullFeatureExtractor(FeatureExtractor):
-    """
-    An extractor that extracts some user-provided features.
-    The structure of the single parameter is demonstrated in the example below.
-
-    This is useful for testing, as we can provide expected values and see if matching works.
-    Also, this is how we represent features deserialized from a freeze file.
-
-    example::
-
-        extractor = NullFeatureExtractor({
-            'base address: 0x401000,
-            'file features': [
-                (0x402345, capa.features.Characteristic('embedded pe')),
-            ],
-            'functions': {
-                0x401000: {
-                    'features': [
-                        (0x401000, capa.features.Characteristic('switch')),
-                    ],
-                    'basic blocks': {
-                        0x401000: {
-                            'features': [
-                                (0x401000, capa.features.Characteristic('tight-loop')),
-                            ],
-                            'instructions': {
-                                0x401000: {
-                                    'features': [
-                                        (0x401000, capa.features.Characteristic('nzxor')),
-                                    ],
-                                },
-                                0x401002: ...
-                            }
-                        },
-                        0x401005: ...
-                    }
-                },
-                0x40200: ...
-            }
-        )
-    """
-
-    def __init__(self, features):
-        super(NullFeatureExtractor, self).__init__()
-        self.features = features
-
-    def get_base_address(self):
-        return self.features["base address"]
-
-    def extract_file_features(self):
-        for p in self.features.get("file features", []):
-            va, feature = p
-            yield feature, va
-
-    def get_functions(self):
-        for va in sorted(self.features["functions"].keys()):
-            yield va
-
-    def extract_function_features(self, f):
-        for p in self.features.get("functions", {}).get(f, {}).get("features", []):  # noqa: E127 line over-indented
-            va, feature = p
-            yield feature, va
-
-    def get_basic_blocks(self, f):
-        for va in sorted(
-            self.features.get("functions", {})  # noqa: E127 line over-indented
-            .get(f, {})
-            .get("basic blocks", {})
-            .keys()
-        ):
-            yield va
-
-    def extract_basic_block_features(self, f, bb):
-        for p in (
-            self.features.get("functions", {})  # noqa: E127 line over-indented
-            .get(f, {})
-            .get("basic blocks", {})
-            .get(bb, {})
-            .get("features", [])
-        ):
-            va, feature = p
-            yield feature, va
-
-    def get_instructions(self, f, bb):
-        for va in sorted(
-            self.features.get("functions", {})  # noqa: E127 line over-indented
-            .get(f, {})
-            .get("basic blocks", {})
-            .get(bb, {})
-            .get("instructions", {})
-            .keys()
-        ):
-            yield va
-
-    def extract_insn_features(self, f, bb, insn):
-        for p in (
-            self.features.get("functions", {})  # noqa: E127 line over-indented
-            .get(f, {})
-            .get("basic blocks", {})
-            .get(bb, {})
-            .get("instructions", {})
-            .get(insn, {})
-            .get("features", [])
-        ):
-            va, feature = p
-            yield feature, va

capa/features/extractors/base_extractor.py

@@ -0,0 +1,264 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import abc
+import dataclasses
+from typing import Any, Dict, Tuple, Union, Iterator
+from dataclasses import dataclass
+
+import capa.features.address
+from capa.features.common import Feature
+from capa.features.address import Address, AbsoluteVirtualAddress
+
+# feature extractors may reference functions, BBs, insns by opaque handle values.
+# you can use the `.address` property to get and render the address of the feature.
+#
+# these handles are only consumed by routines on
+# the feature extractor from which they were created.
+
+
+@dataclass
+class FunctionHandle:
+    """reference to a function recognized by a feature extractor.
+
+    Attributes:
+        address: the address of the function.
+        inner: extractor-specific data.
+        ctx: a context object for the extractor.
+    """
+
+    address: Address
+    inner: Any
+    ctx: Dict[str, Any] = dataclasses.field(default_factory=dict)
+
+
+@dataclass
+class BBHandle:
+    """reference to a basic block recognized by a feature extractor.
+
+    Attributes:
+        address: the address of the basic block start address.
+        inner: extractor-specific data.
+    """
+
+    address: Address
+    inner: Any
+
+
+@dataclass
+class InsnHandle:
+    """reference to a instruction recognized by a feature extractor.
+
+    Attributes:
+        address: the address of the instruction address.
+        inner: extractor-specific data.
+    """
+
+    address: Address
+    inner: Any
+
+
+class FeatureExtractor:
+    """
+    FeatureExtractor defines the interface for fetching features from a sample.
+
+    There may be multiple backends that support fetching features for capa.
+    For example, we use vivisect by default, but also want to support saving
+     and restoring features from a JSON file.
+    When we restore the features, we'd like to use exactly the same matching logic
+     to find matching rules.
+    Therefore, we can define a FeatureExtractor that provides features from the
+     serialized JSON file and do matching without a binary analysis pass.
+    Also, this provides a way to hook in an IDA backend.
+
+    This class is not instantiated directly; it is the base class for other implementations.
+    """
+
+    __metaclass__ = abc.ABCMeta
+
+    def __init__(self):
+        #
+        # note: a subclass should define ctor parameters for its own use.
+        #  for example, the Vivisect feature extract might require the vw and/or path.
+        # this base class doesn't know what to do with that info, though.
+        #
+        super().__init__()
+
+    @abc.abstractmethod
+    def get_base_address(self) -> Union[AbsoluteVirtualAddress, capa.features.address._NoAddress]:
+        """
+        fetch the preferred load address at which the sample was analyzed.
+
+        when the base address is `NO_ADDRESS`, then the loader has no concept of a preferred load address.
+        such as: shellcode, .NET modules, etc.
+        in these scenarios, RelativeVirtualAddresses aren't used.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def extract_global_features(self) -> Iterator[Tuple[Feature, Address]]:
+        """
+        extract features found at every scope ("global").
+
+        example::
+
+            extractor = VivisectFeatureExtractor(vw, path)
+            for feature, va in extractor.get_global_features():
+                print('0x%x: %s', va, feature)
+
+        yields:
+          Tuple[Feature, Address]: feature and its location
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def extract_file_features(self) -> Iterator[Tuple[Feature, Address]]:
+        """
+        extract file-scope features.
+
+        example::
+
+            extractor = VivisectFeatureExtractor(vw, path)
+            for feature, va in extractor.get_file_features():
+                print('0x%x: %s', va, feature)
+
+        yields:
+          Tuple[Feature, Address]: feature and its location
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def get_functions(self) -> Iterator[FunctionHandle]:
+        """
+        enumerate the functions and provide opaque values that will
+         subsequently be provided to `.extract_function_features()`, etc.
+        """
+        raise NotImplementedError()
+
+    def is_library_function(self, addr: Address) -> bool:
+        """
+        is the given address a library function?
+        the backend may implement its own function matching algorithm, or none at all.
+        we accept an address here, rather than function object,
+         to handle addresses identified in instructions.
+
+        this information is used to:
+          - filter out matches in library functions (by default), and
+          - recognize when to fetch symbol names for called (non-API) functions
+
+        args:
+          addr (Address): the address of a function.
+
+        returns:
+          bool: True if the given address is the start of a library function.
+        """
+        return False
+
+    def get_function_name(self, addr: Address) -> str:
+        """
+        fetch any recognized name for the given address.
+        this is only guaranteed to return a value when the given function is a recognized library function.
+        we accept a VA here, rather than function object, to handle addresses identified in instructions.
+
+        args:
+          addr (Address): the address of a function.
+
+        returns:
+          str: the function name
+
+        raises:
+          KeyError: when the given function does not have a name.
+        """
+        raise KeyError(addr)
+
+    @abc.abstractmethod
+    def extract_function_features(self, f: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+        """
+        extract function-scope features.
+        the arguments are opaque values previously provided by `.get_functions()`, etc.
+
+        example::
+
+            extractor = VivisectFeatureExtractor(vw, path)
+            for function in extractor.get_functions():
+                for feature, address in extractor.extract_function_features(function):
+                    print('0x%x: %s', address, feature)
+
+        args:
+          f [FunctionHandle]: an opaque value previously fetched from `.get_functions()`.
+
+        yields:
+          Tuple[Feature, Address]: feature and its location
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def get_basic_blocks(self, f: FunctionHandle) -> Iterator[BBHandle]:
+        """
+        enumerate the basic blocks in the given function and provide opaque values that will
+         subsequently be provided to `.extract_basic_block_features()`, etc.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def extract_basic_block_features(self, f: FunctionHandle, bb: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+        """
+        extract basic block-scope features.
+        the arguments are opaque values previously provided by `.get_functions()`, etc.
+
+        example::
+
+            extractor = VivisectFeatureExtractor(vw, path)
+            for function in extractor.get_functions():
+                for bb in extractor.get_basic_blocks(function):
+                    for feature, address in extractor.extract_basic_block_features(function, bb):
+                        print('0x%x: %s', address, feature)
+
+        args:
+          f [FunctionHandle]: an opaque value previously fetched from `.get_functions()`.
+          bb [BBHandle]: an opaque value previously fetched from `.get_basic_blocks()`.
+
+        yields:
+          Tuple[Feature, Address]: feature and its location
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def get_instructions(self, f: FunctionHandle, bb: BBHandle) -> Iterator[InsnHandle]:
+        """
+        enumerate the instructions in the given basic block and provide opaque values that will
+         subsequently be provided to `.extract_insn_features()`, etc.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def extract_insn_features(
+        self, f: FunctionHandle, bb: BBHandle, insn: InsnHandle
+    ) -> Iterator[Tuple[Feature, Address]]:
+        """
+        extract instruction-scope features.
+        the arguments are opaque values previously provided by `.get_functions()`, etc.
+
+        example::
+
+            extractor = VivisectFeatureExtractor(vw, path)
+            for function in extractor.get_functions():
+                for bb in extractor.get_basic_blocks(function):
+                    for insn in extractor.get_instructions(function, bb):
+                        for feature, address in extractor.extract_insn_features(function, bb, insn):
+                            print('0x%x: %s', address, feature)
+
+        args:
+          f [FunctionHandle]: an opaque value previously fetched from `.get_functions()`.
+          bb [BBHandle]: an opaque value previously fetched from `.get_basic_blocks()`.
+          insn [InsnHandle]: an opaque value previously fetched from `.get_instructions()`.
+
+        yields:
+          Tuple[Feature, Address]: feature and its location
+        """
+        raise NotImplementedError()

capa/features/extractors/binja/basicblock.py

@@ -0,0 +1,184 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import string
+import struct
+from typing import Tuple, Iterator
+
+from binaryninja import Function, Settings
+from binaryninja import BasicBlock as BinjaBasicBlock
+from binaryninja import (
+    BinaryView,
+    SymbolType,
+    RegisterValueType,
+    VariableSourceType,
+    MediumLevelILSetVar,
+    MediumLevelILOperation,
+    MediumLevelILBasicBlock,
+    MediumLevelILInstruction,
+)
+
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address
+from capa.features.basicblock import BasicBlock
+from capa.features.extractors.helpers import MIN_STACKSTRING_LEN
+from capa.features.extractors.base_extractor import BBHandle, FunctionHandle
+
+use_const_outline: bool = False
+settings: Settings = Settings()
+if settings.contains("analysis.outlining.builtins") and settings.get_bool("analysis.outlining.builtins"):
+    use_const_outline = True
+
+
+def get_printable_len_ascii(s: bytes) -> int:
+    """Return string length if all operand bytes are ascii or utf16-le printable"""
+    count = 0
+    for c in s:
+        if c == 0:
+            return count
+        if c < 127 and chr(c) in string.printable:
+            count += 1
+    return count
+
+
+def get_printable_len_wide(s: bytes) -> int:
+    """Return string length if all operand bytes are ascii or utf16-le printable"""
+    if all(c == 0x00 for c in s[1::2]):
+        return get_printable_len_ascii(s[::2])
+    return 0
+
+
+def get_stack_string_len(f: Function, il: MediumLevelILInstruction) -> int:
+    bv: BinaryView = f.view
+
+    if il.operation != MediumLevelILOperation.MLIL_CALL:
+        return 0
+
+    target = il.dest
+    if target.operation not in [MediumLevelILOperation.MLIL_CONST, MediumLevelILOperation.MLIL_CONST_PTR]:
+        return 0
+
+    addr = target.value.value
+    sym = bv.get_symbol_at(addr)
+    if not sym or sym.type != SymbolType.LibraryFunctionSymbol:
+        return 0
+
+    if sym.name not in ["__builtin_strncpy", "__builtin_strcpy", "__builtin_wcscpy"]:
+        return 0
+
+    if len(il.params) < 2:
+        return 0
+
+    dest = il.params[0]
+    if dest.operation in [MediumLevelILOperation.MLIL_ADDRESS_OF, MediumLevelILOperation.MLIL_VAR]:
+        var = dest.src
+    else:
+        return 0
+
+    if var.source_type != VariableSourceType.StackVariableSourceType:
+        return 0
+
+    src = il.params[1]
+    if src.value.type != RegisterValueType.ConstantDataAggregateValue:
+        return 0
+
+    s = f.get_constant_data(RegisterValueType.ConstantDataAggregateValue, src.value.value)
+    return max(get_printable_len_ascii(bytes(s)), get_printable_len_wide(bytes(s)))
+
+
+def get_printable_len(il: MediumLevelILSetVar) -> int:
+    """Return string length if all operand bytes are ascii or utf16-le printable"""
+    width = il.dest.type.width
+    value = il.src.value.value
+
+    if width == 1:
+        chars = struct.pack("<B", value & 0xFF)
+    elif width == 2:
+        chars = struct.pack("<H", value & 0xFFFF)
+    elif width == 4:
+        chars = struct.pack("<I", value & 0xFFFFFFFF)
+    elif width == 8:
+        chars = struct.pack("<Q", value & 0xFFFFFFFFFFFFFFFF)
+    else:
+        return 0
+
+    def is_printable_ascii(chars_: bytes):
+        return all(c < 127 and chr(c) in string.printable for c in chars_)
+
+    def is_printable_utf16le(chars_: bytes):
+        if all(c == 0x00 for c in chars_[1::2]):
+            return is_printable_ascii(chars_[::2])
+
+    if is_printable_ascii(chars):
+        return width
+
+    if is_printable_utf16le(chars):
+        return width // 2
+
+    return 0
+
+
+def is_mov_imm_to_stack(il: MediumLevelILInstruction) -> bool:
+    """verify instruction moves immediate onto stack"""
+    if il.operation != MediumLevelILOperation.MLIL_SET_VAR:
+        return False
+
+    if il.src.operation != MediumLevelILOperation.MLIL_CONST:
+        return False
+
+    if il.dest.source_type != VariableSourceType.StackVariableSourceType:
+        return False
+
+    return True
+
+
+def bb_contains_stackstring(f: Function, bb: MediumLevelILBasicBlock) -> bool:
+    """check basic block for stackstring indicators
+
+    true if basic block contains enough moves of constant bytes to the stack
+    """
+    count = 0
+    for il in bb:
+        if use_const_outline:
+            count += get_stack_string_len(f, il)
+        else:
+            if is_mov_imm_to_stack(il):
+                count += get_printable_len(il)
+
+    if count > MIN_STACKSTRING_LEN:
+        return True
+    return False
+
+
+def extract_bb_stackstring(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract stackstring indicators from basic block"""
+    bb: Tuple[BinjaBasicBlock, MediumLevelILBasicBlock] = bbh.inner
+    if bb[1] is not None and bb_contains_stackstring(fh.inner, bb[1]):
+        yield Characteristic("stack string"), bbh.address
+
+
+def extract_bb_tight_loop(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract tight loop indicators from a basic block"""
+    bb: Tuple[BinjaBasicBlock, MediumLevelILBasicBlock] = bbh.inner
+    for edge in bb[0].outgoing_edges:
+        if edge.target.start == bb[0].start:
+            yield Characteristic("tight loop"), bbh.address
+
+
+def extract_features(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract basic block features"""
+    for bb_handler in BASIC_BLOCK_HANDLERS:
+        for feature, addr in bb_handler(fh, bbh):
+            yield feature, addr
+    yield BasicBlock(), bbh.address
+
+
+BASIC_BLOCK_HANDLERS = (
+    extract_bb_tight_loop,
+    extract_bb_stackstring,
+)

capa/features/extractors/binja/extractor.py

@@ -0,0 +1,75 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import List, Tuple, Iterator
+
+import binaryninja as binja
+
+import capa.features.extractors.elf
+import capa.features.extractors.binja.file
+import capa.features.extractors.binja.insn
+import capa.features.extractors.binja.global_
+import capa.features.extractors.binja.function
+import capa.features.extractors.binja.basicblock
+from capa.features.common import Feature
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle, FeatureExtractor
+
+
+class BinjaFeatureExtractor(FeatureExtractor):
+    def __init__(self, bv: binja.BinaryView):
+        super().__init__()
+        self.bv = bv
+        self.global_features: List[Tuple[Feature, Address]] = []
+        self.global_features.extend(capa.features.extractors.binja.file.extract_file_format(self.bv))
+        self.global_features.extend(capa.features.extractors.binja.global_.extract_os(self.bv))
+        self.global_features.extend(capa.features.extractors.binja.global_.extract_arch(self.bv))
+
+    def get_base_address(self):
+        return AbsoluteVirtualAddress(self.bv.start)
+
+    def extract_global_features(self):
+        yield from self.global_features
+
+    def extract_file_features(self):
+        yield from capa.features.extractors.binja.file.extract_features(self.bv)
+
+    def get_functions(self) -> Iterator[FunctionHandle]:
+        for f in self.bv.functions:
+            yield FunctionHandle(address=AbsoluteVirtualAddress(f.start), inner=f)
+
+    def extract_function_features(self, fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.binja.function.extract_features(fh)
+
+    def get_basic_blocks(self, fh: FunctionHandle) -> Iterator[BBHandle]:
+        f: binja.Function = fh.inner
+        # Set up a MLIL basic block dict look up to associate the disassembly basic block with its MLIL basic block
+        mlil_lookup = {}
+        for mlil_bb in f.mlil.basic_blocks:
+            mlil_lookup[mlil_bb.source_block.start] = mlil_bb
+
+        for bb in f.basic_blocks:
+            mlil_bb = mlil_lookup.get(bb.start)
+
+            yield BBHandle(address=AbsoluteVirtualAddress(bb.start), inner=(bb, mlil_bb))
+
+    def extract_basic_block_features(self, fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.binja.basicblock.extract_features(fh, bbh)
+
+    def get_instructions(self, fh: FunctionHandle, bbh: BBHandle) -> Iterator[InsnHandle]:
+        import capa.features.extractors.binja.helpers as binja_helpers
+
+        bb: Tuple[binja.BasicBlock, binja.MediumLevelILBasicBlock] = bbh.inner
+        addr = bb[0].start
+
+        for text, length in bb[0]:
+            insn = binja_helpers.DisassemblyInstruction(addr, length, text)
+            yield InsnHandle(address=AbsoluteVirtualAddress(addr), inner=insn)
+            addr += length
+
+    def extract_insn_features(self, fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle):
+        yield from capa.features.extractors.binja.insn.extract_features(fh, bbh, ih)

capa/features/extractors/binja/file.py

@@ -0,0 +1,167 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import struct
+from typing import Tuple, Iterator
+
+from binaryninja import Segment, BinaryView, SymbolType, SymbolBinding
+
+import capa.features.extractors.common
+import capa.features.extractors.helpers
+import capa.features.extractors.strings
+from capa.features.file import Export, Import, Section, FunctionName
+from capa.features.common import FORMAT_PE, FORMAT_ELF, Format, String, Feature, Characteristic
+from capa.features.address import NO_ADDRESS, Address, FileOffsetAddress, AbsoluteVirtualAddress
+from capa.features.extractors.binja.helpers import unmangle_c_name
+
+
+def check_segment_for_pe(bv: BinaryView, seg: Segment) -> Iterator[Tuple[int, int]]:
+    """check segment for embedded PE
+
+    adapted for binja from:
+    https://github.com/vivisect/vivisect/blob/7be4037b1cecc4551b397f840405a1fc606f9b53/PE/carve.py#L19
+    """
+    mz_xor = [
+        (
+            capa.features.extractors.helpers.xor_static(b"MZ", i),
+            capa.features.extractors.helpers.xor_static(b"PE", i),
+            i,
+        )
+        for i in range(256)
+    ]
+
+    todo = []
+    # If this is the first segment of the binary, skip the first bytes. Otherwise, there will always be a matched
+    # PE at the start of the binaryview.
+    start = seg.start
+    if bv.view_type == "PE" and start == bv.start:
+        start += 1
+
+    for mzx, pex, i in mz_xor:
+        for off, _ in bv.find_all_data(start, seg.end, mzx):
+            todo.append((off, mzx, pex, i))
+
+    while len(todo):
+        off, mzx, pex, i = todo.pop()
+
+        # The MZ header has one field we will check e_lfanew is at 0x3c
+        e_lfanew = off + 0x3C
+
+        if seg.end < (e_lfanew + 4):
+            continue
+
+        newoff = struct.unpack("<I", capa.features.extractors.helpers.xor_static(bv.read(e_lfanew, 4), i))[0]
+
+        peoff = off + newoff
+        if seg.end < (peoff + 2):
+            continue
+
+        if bv.read(peoff, 2) == pex:
+            yield off, i
+
+
+def extract_file_embedded_pe(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract embedded PE features"""
+    for seg in bv.segments:
+        for ea, _ in check_segment_for_pe(bv, seg):
+            yield Characteristic("embedded pe"), FileOffsetAddress(ea)
+
+
+def extract_file_export_names(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract function exports"""
+    for sym in bv.get_symbols_of_type(SymbolType.FunctionSymbol):
+        if sym.binding in [SymbolBinding.GlobalBinding, SymbolBinding.WeakBinding]:
+            name = sym.short_name
+            yield Export(name), AbsoluteVirtualAddress(sym.address)
+            unmangled_name = unmangle_c_name(name)
+            if name != unmangled_name:
+                yield Export(unmangled_name), AbsoluteVirtualAddress(sym.address)
+
+
+def extract_file_import_names(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract function imports
+
+    1. imports by ordinal:
+     - modulename.#ordinal
+
+    2. imports by name, results in two features to support importname-only
+       matching:
+     - modulename.importname
+     - importname
+    """
+    for sym in bv.get_symbols_of_type(SymbolType.ImportAddressSymbol):
+        lib_name = str(sym.namespace)
+        addr = AbsoluteVirtualAddress(sym.address)
+        for name in capa.features.extractors.helpers.generate_symbols(lib_name, sym.short_name):
+            yield Import(name), addr
+
+        ordinal = sym.ordinal
+        if ordinal != 0 and (lib_name != ""):
+            ordinal_name = f"#{ordinal}"
+            for name in capa.features.extractors.helpers.generate_symbols(lib_name, ordinal_name):
+                yield Import(name), addr
+
+
+def extract_file_section_names(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract section names"""
+    for name, section in bv.sections.items():
+        yield Section(name), AbsoluteVirtualAddress(section.start)
+
+
+def extract_file_strings(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract ASCII and UTF-16 LE strings"""
+    for s in bv.strings:
+        yield String(s.value), FileOffsetAddress(s.start)
+
+
+def extract_file_function_names(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """
+    extract the names of statically-linked library functions.
+    """
+    for sym_name in bv.symbols:
+        for sym in bv.symbols[sym_name]:
+            if sym.type == SymbolType.LibraryFunctionSymbol:
+                name = sym.short_name
+                yield FunctionName(name), sym.address
+                if name.startswith("_"):
+                    # some linkers may prefix linked routines with a `_` to avoid name collisions.
+                    # extract features for both the mangled and un-mangled representations.
+                    # e.g. `_fwrite` -> `fwrite`
+                    # see: https://stackoverflow.com/a/2628384/87207
+                    yield FunctionName(name[1:]), sym.address
+
+
+def extract_file_format(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    view_type = bv.view_type
+    if view_type in ["PE", "COFF"]:
+        yield Format(FORMAT_PE), NO_ADDRESS
+    elif view_type == "ELF":
+        yield Format(FORMAT_ELF), NO_ADDRESS
+    elif view_type == "Raw":
+        # no file type to return when processing a binary file, but we want to continue processing
+        return
+    else:
+        raise NotImplementedError(f"unexpected file format: {view_type}")
+
+
+def extract_features(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    """extract file features"""
+    for file_handler in FILE_HANDLERS:
+        for feature, addr in file_handler(bv):
+            yield feature, addr
+
+
+FILE_HANDLERS = (
+    extract_file_export_names,
+    extract_file_import_names,
+    extract_file_strings,
+    extract_file_section_names,
+    extract_file_embedded_pe,
+    extract_file_function_names,
+    extract_file_format,
+)

capa/features/extractors/binja/find_binja_api.py

@@ -0,0 +1,35 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import subprocess
+from pathlib import Path
+
+# When the script gets executed as a standalone executable (via PyInstaller), `import binaryninja` does not work because
+# we have excluded the binaryninja module in `pyinstaller.spec`. The trick here is to call the system Python and try
+# to find out the path of the binaryninja module that has been installed.
+# Note, including the binaryninja module in the `pyintaller.spec` would not work, since the binaryninja module tries to
+# find the binaryninja core e.g., `libbinaryninjacore.dylib`, using a relative path. And this does not work when the
+# binaryninja module is extracted by the PyInstaller.
+code = r"""
+from pathlib import Path
+from importlib import util
+spec = util.find_spec('binaryninja')
+if spec is not None:
+    if len(spec.submodule_search_locations) > 0:
+            path = Path(spec.submodule_search_locations[0])
+            # encode the path with utf8 then convert to hex, make sure it can be read and restored properly
+            print(str(path.parent).encode('utf8').hex())
+"""
+
+
+def find_binja_path() -> Path:
+    raw_output = subprocess.check_output(["python", "-c", code]).decode("ascii").strip()
+    return Path(bytes.fromhex(raw_output).decode("utf8"))
+
+
+if __name__ == "__main__":
+    print(find_binja_path())

capa/features/extractors/binja/function.py

@@ -0,0 +1,68 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Tuple, Iterator
+
+from binaryninja import Function, BinaryView, LowLevelILOperation
+
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors import loops
+from capa.features.extractors.base_extractor import FunctionHandle
+
+
+def extract_function_calls_to(fh: FunctionHandle):
+    """extract callers to a function"""
+    func: Function = fh.inner
+
+    for caller in func.caller_sites:
+        # Everything that is a code reference to the current function is considered a caller, which actually includes
+        # many other references that are NOT a caller. For example, an instruction `push function_start` will also be
+        # considered a caller to the function
+        if caller.llil is not None and caller.llil.operation in [
+            LowLevelILOperation.LLIL_CALL,
+            LowLevelILOperation.LLIL_CALL_STACK_ADJUST,
+            LowLevelILOperation.LLIL_JUMP,
+            LowLevelILOperation.LLIL_TAILCALL,
+        ]:
+            yield Characteristic("calls to"), AbsoluteVirtualAddress(caller.address)
+
+
+def extract_function_loop(fh: FunctionHandle):
+    """extract loop indicators from a function"""
+    func: Function = fh.inner
+
+    edges = []
+
+    # construct control flow graph
+    for bb in func.basic_blocks:
+        for edge in bb.outgoing_edges:
+            edges.append((bb.start, edge.target.start))
+
+    if loops.has_loop(edges):
+        yield Characteristic("loop"), fh.address
+
+
+def extract_recursive_call(fh: FunctionHandle):
+    """extract recursive function call"""
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+    if bv is None:
+        return
+
+    for ref in bv.get_code_refs(func.start):
+        if ref.function == func:
+            yield Characteristic("recursive call"), fh.address
+
+
+def extract_features(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+    for func_handler in FUNCTION_HANDLERS:
+        for feature, addr in func_handler(fh):
+            yield feature, addr
+
+
+FUNCTION_HANDLERS = (extract_function_calls_to, extract_function_loop, extract_recursive_call)

capa/features/extractors/binja/global_.py

@@ -0,0 +1,60 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+from typing import Tuple, Iterator
+
+from binaryninja import BinaryView
+
+from capa.features.common import OS, OS_MACOS, ARCH_I386, ARCH_AMD64, OS_WINDOWS, Arch, Feature
+from capa.features.address import NO_ADDRESS, Address
+
+logger = logging.getLogger(__name__)
+
+
+def extract_os(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    name = bv.platform.name
+    if "-" in name:
+        name = name.split("-")[0]
+
+    if name == "windows":
+        yield OS(OS_WINDOWS), NO_ADDRESS
+
+    elif name == "macos":
+        yield OS(OS_MACOS), NO_ADDRESS
+
+    elif name in ["linux", "freebsd", "decree"]:
+        yield OS(name), NO_ADDRESS
+
+    else:
+        # we likely end up here:
+        #  1. handling shellcode, or
+        #  2. handling a new file format (e.g. macho)
+        #
+        # for (1) we can't do much - its shellcode and all bets are off.
+        # we could maybe accept a further CLI argument to specify the OS,
+        # but i think this would be rarely used.
+        # rules that rely on OS conditions will fail to match on shellcode.
+        #
+        # for (2), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported file format: %s, will not guess OS", name)
+        return
+
+
+def extract_arch(bv: BinaryView) -> Iterator[Tuple[Feature, Address]]:
+    arch = bv.arch.name
+    if arch == "x86_64":
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+    elif arch == "x86":
+        yield Arch(ARCH_I386), NO_ADDRESS
+    else:
+        # we likely end up here:
+        #  1. handling a new architecture (e.g. aarch64)
+        #
+        # for (1), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported architecture: %s", arch)
+        return

capa/features/extractors/binja/helpers.py

@@ -0,0 +1,53 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import re
+from typing import List, Callable
+from dataclasses import dataclass
+
+from binaryninja import LowLevelILInstruction
+from binaryninja.architecture import InstructionTextToken
+
+
+@dataclass
+class DisassemblyInstruction:
+    address: int
+    length: int
+    text: List[InstructionTextToken]
+
+
+LLIL_VISITOR = Callable[[LowLevelILInstruction, LowLevelILInstruction, int], bool]
+
+
+def visit_llil_exprs(il: LowLevelILInstruction, func: LLIL_VISITOR):
+    # BN does not really support operand index at the disassembly level, so use the LLIL operand index as a substitute.
+    # Note, this is NOT always guaranteed to be the same as disassembly operand.
+    for i, op in enumerate(il.operands):
+        if isinstance(op, LowLevelILInstruction) and func(op, il, i):
+            visit_llil_exprs(op, func)
+
+
+def unmangle_c_name(name: str) -> str:
+    # https://learn.microsoft.com/en-us/cpp/build/reference/decorated-names?view=msvc-170#FormatC
+    # Possible variations for BaseThreadInitThunk:
+    # @BaseThreadInitThunk@12
+    # _BaseThreadInitThunk
+    # _BaseThreadInitThunk@12
+    # It is also possible for a function to have a `Stub` appended to its name:
+    # _lstrlenWStub@4
+
+    # A small optimization to avoid running the regex too many times
+    # this still increases the unit test execution time from 170s to 200s, should be able to accelerate it
+    #
+    # TODO(xusheng): performance optimizations to improve test execution time
+    # https://github.com/mandiant/capa/issues/1610
+    if name[0] in ["@", "_"]:
+        match = re.match(r"^[@|_](.*?)(Stub)?(@\d+)?$", name)
+        if match:
+            return match.group(1)
+
+    return name

capa/features/extractors/binja/insn.py

@@ -0,0 +1,582 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Any, List, Tuple, Iterator, Optional
+
+from binaryninja import Function
+from binaryninja import BasicBlock as BinjaBasicBlock
+from binaryninja import (
+    BinaryView,
+    ILRegister,
+    SymbolType,
+    BinaryReader,
+    RegisterValueType,
+    LowLevelILOperation,
+    LowLevelILInstruction,
+)
+
+import capa.features.extractors.helpers
+from capa.features.insn import API, MAX_STRUCTURE_SIZE, Number, Offset, Mnemonic, OperandNumber, OperandOffset
+from capa.features.common import MAX_BYTES_FEATURE_SIZE, Bytes, String, Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.binja.helpers import DisassemblyInstruction, visit_llil_exprs
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle
+
+# security cookie checks may perform non-zeroing XORs, these are expected within a certain
+# byte range within the first and returning basic blocks, this helps to reduce FP features
+SECURITY_COOKIE_BYTES_DELTA = 0x40
+
+
+# check if a function is a stub function to another function/symbol. The criteria is:
+# 1. The function must only have one basic block
+# 2. The function must only make one call/jump to another address
+# If the function being checked is a stub function, returns the target address. Otherwise, return None.
+def is_stub_function(bv: BinaryView, addr: int) -> Optional[int]:
+    funcs = bv.get_functions_at(addr)
+    for func in funcs:
+        if len(func.basic_blocks) != 1:
+            continue
+
+        call_count = 0
+        call_target = None
+        for il in func.llil.instructions:
+            if il.operation in [
+                LowLevelILOperation.LLIL_CALL,
+                LowLevelILOperation.LLIL_CALL_STACK_ADJUST,
+                LowLevelILOperation.LLIL_JUMP,
+                LowLevelILOperation.LLIL_TAILCALL,
+            ]:
+                call_count += 1
+                if il.dest.value.type in [
+                    RegisterValueType.ImportedAddressValue,
+                    RegisterValueType.ConstantValue,
+                    RegisterValueType.ConstantPointerValue,
+                ]:
+                    call_target = il.dest.value.value
+
+        if call_count == 1 and call_target is not None:
+            return call_target
+
+    return None
+
+
+def extract_insn_api_features(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction API features
+
+    example:
+       call dword [0x00473038]
+    """
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+
+    for llil in func.get_llils_at(ih.address):
+        if llil.operation in [
+            LowLevelILOperation.LLIL_CALL,
+            LowLevelILOperation.LLIL_CALL_STACK_ADJUST,
+            LowLevelILOperation.LLIL_JUMP,
+            LowLevelILOperation.LLIL_TAILCALL,
+        ]:
+            if llil.dest.value.type not in [
+                RegisterValueType.ImportedAddressValue,
+                RegisterValueType.ConstantValue,
+                RegisterValueType.ConstantPointerValue,
+            ]:
+                continue
+            address = llil.dest.value.value
+            candidate_addrs = [address]
+            stub_addr = is_stub_function(bv, address)
+            if stub_addr is not None:
+                candidate_addrs.append(stub_addr)
+
+            for address in candidate_addrs:
+                sym = func.view.get_symbol_at(address)
+                if sym is None or sym.type not in [SymbolType.ImportAddressSymbol, SymbolType.ImportedFunctionSymbol]:
+                    continue
+
+                sym_name = sym.short_name
+
+                lib_name = ""
+                import_lib = bv.lookup_imported_object_library(sym.address)
+                if import_lib is not None:
+                    lib_name = import_lib[0].name
+                    if lib_name.endswith(".dll"):
+                        lib_name = lib_name[:-4]
+                    elif lib_name.endswith(".so"):
+                        lib_name = lib_name[:-3]
+
+                for name in capa.features.extractors.helpers.generate_symbols(lib_name, sym_name):
+                    yield API(name), ih.address
+
+                if sym_name.startswith("_"):
+                    for name in capa.features.extractors.helpers.generate_symbols(lib_name, sym_name[1:]):
+                        yield API(name), ih.address
+
+
+def extract_insn_number_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction number features
+    example:
+        push    3136B0h         ; dwControlCode
+    """
+    func: Function = fh.inner
+
+    results: List[Tuple[Any[Number, OperandNumber], Address]] = []
+
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        if il.operation == LowLevelILOperation.LLIL_LOAD:
+            return False
+
+        if il.operation not in [LowLevelILOperation.LLIL_CONST, LowLevelILOperation.LLIL_CONST_PTR]:
+            return True
+
+        for op in parent.operands:
+            if isinstance(op, ILRegister) and op.name in ["esp", "ebp", "rsp", "rbp", "sp"]:
+                return False
+            elif isinstance(op, LowLevelILInstruction) and op.operation == LowLevelILOperation.LLIL_REG:
+                if op.src.name in ["esp", "ebp", "rsp", "rbp", "sp"]:
+                    return False
+
+        raw_value = il.value.value
+        if parent.operation == LowLevelILOperation.LLIL_SUB:
+            raw_value = -raw_value
+
+        results.append((Number(raw_value), ih.address))
+        results.append((OperandNumber(index, raw_value), ih.address))
+
+        return False
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    yield from results
+
+
+def extract_insn_bytes_features(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse referenced byte sequences
+    example:
+        push    offset iid_004118d4_IShellLinkA ; riid
+    """
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+
+    candidate_addrs = set()
+
+    llil = func.get_llil_at(ih.address)
+    if llil is None or llil.operation in [LowLevelILOperation.LLIL_CALL, LowLevelILOperation.LLIL_CALL_STACK_ADJUST]:
+        return
+
+    for ref in bv.get_code_refs_from(ih.address):
+        if ref == ih.address:
+            continue
+
+        if len(bv.get_functions_containing(ref)) > 0:
+            continue
+
+        candidate_addrs.add(ref)
+
+    # collect candidate address by enumerating all integers, https://github.com/Vector35/binaryninja-api/issues/3966
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        if il.operation in [LowLevelILOperation.LLIL_CONST, LowLevelILOperation.LLIL_CONST_PTR]:
+            value = il.value.value
+            if value > 0:
+                candidate_addrs.add(value)
+            return False
+
+        return True
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    for addr in candidate_addrs:
+        extracted_bytes = bv.read(addr, MAX_BYTES_FEATURE_SIZE)
+        if extracted_bytes and not capa.features.extractors.helpers.all_zeros(extracted_bytes):
+            if bv.get_string_at(addr) is None:
+                # don't extract byte features for obvious strings
+                yield Bytes(extracted_bytes), ih.address
+
+
+def extract_insn_string_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction string features
+
+    example:
+        push offset aAcr     ; "ACR  > "
+    """
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+
+    candidate_addrs = set()
+
+    # collect candidate address from code refs directly
+    for ref in bv.get_code_refs_from(ih.address):
+        if ref == ih.address:
+            continue
+
+        if len(bv.get_functions_containing(ref)) > 0:
+            continue
+
+        candidate_addrs.add(ref)
+
+    # collect candidate address by enumerating all integers, https://github.com/Vector35/binaryninja-api/issues/3966
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        if il.operation in [LowLevelILOperation.LLIL_CONST, LowLevelILOperation.LLIL_CONST_PTR]:
+            value = il.value.value
+            if value > 0:
+                candidate_addrs.add(value)
+            return False
+
+        return True
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    # Now we have all the candidate address, check them for string or pointer to string
+    br = BinaryReader(bv)
+    for addr in candidate_addrs:
+        found = bv.get_string_at(addr)
+        if found:
+            yield String(found.value), ih.address
+
+        br.seek(addr)
+        pointer = None
+        if bv.arch.address_size == 4:
+            pointer = br.read32()
+        elif bv.arch.address_size == 8:
+            pointer = br.read64()
+
+        if pointer is not None:
+            found = bv.get_string_at(pointer)
+            if found:
+                yield String(found.value), ih.address
+
+
+def extract_insn_offset_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction structure offset features
+
+    example:
+        .text:0040112F cmp [esi+4], ebx
+    """
+    func: Function = fh.inner
+
+    results: List[Tuple[Any[Offset, OperandOffset], Address]] = []
+    address_size = func.view.arch.address_size * 8
+
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        #  The most common case, read/write dereference to something like `dword [eax+0x28]`
+        if il.operation in [LowLevelILOperation.LLIL_ADD, LowLevelILOperation.LLIL_SUB]:
+            left = il.left
+            right = il.right
+            # Exclude offsets based on stack/franme pointers
+            if left.operation == LowLevelILOperation.LLIL_REG and left.src.name in ["esp", "ebp", "rsp", "rbp", "sp"]:
+                return True
+
+            if right.operation != LowLevelILOperation.LLIL_CONST:
+                return True
+
+            raw_value = right.value.value
+            # If this is not a dereference, then this must be an add and the offset must be in the range \
+            # [0, MAX_STRUCTURE_SIZE]. For example,
+            # add eax, 0x10,
+            # lea ebx, [eax + 1]
+            if parent.operation not in [LowLevelILOperation.LLIL_LOAD, LowLevelILOperation.LLIL_STORE]:
+                if il.operation != LowLevelILOperation.LLIL_ADD or (not 0 < raw_value < MAX_STRUCTURE_SIZE):
+                    return False
+
+            if address_size > 0:
+                # BN also encodes the constant value as two's complement, we need to restore its original value
+                value = capa.features.extractors.helpers.twos_complement(raw_value, address_size)
+            else:
+                value = raw_value
+
+            results.append((Offset(value), ih.address))
+            results.append((OperandOffset(index, value), ih.address))
+            return False
+
+        # An edge case: for code like `push dword [esi]`, we need to generate a feature for offset 0x0
+        elif il.operation in [LowLevelILOperation.LLIL_LOAD, LowLevelILOperation.LLIL_STORE]:
+            if il.operands[0].operation == LowLevelILOperation.LLIL_REG:
+                results.append((Offset(0), ih.address))
+                results.append((OperandOffset(index, 0), ih.address))
+                return False
+
+        return True
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    yield from results
+
+
+def is_nzxor_stack_cookie(f: Function, bb: BinjaBasicBlock, llil: LowLevelILInstruction) -> bool:
+    """check if nzxor exists within stack cookie delta"""
+    # TODO(xusheng): use LLIL SSA to do more accurate analysis
+    # https://github.com/mandiant/capa/issues/1609
+
+    reg_names = []
+    if llil.left.operation == LowLevelILOperation.LLIL_REG:
+        reg_names.append(llil.left.src.name)
+
+    if llil.right.operation == LowLevelILOperation.LLIL_REG:
+        reg_names.append(llil.right.src.name)
+
+    # stack cookie reg should be stack/frame pointer
+    if not any(reg in ["ebp", "esp", "rbp", "rsp", "sp"] for reg in reg_names):
+        return False
+
+    # expect security cookie init in first basic block within first bytes (instructions)
+    if len(bb.incoming_edges) == 0 and llil.address < (bb.start + SECURITY_COOKIE_BYTES_DELTA):
+        return True
+
+    # ... or within last bytes (instructions) before a return
+    if len(bb.outgoing_edges) == 0 and llil.address > (bb.end - SECURITY_COOKIE_BYTES_DELTA):
+        return True
+
+    return False
+
+
+def extract_insn_nzxor_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction non-zeroing XOR instruction
+    ignore expected non-zeroing XORs, e.g. security cookies
+    """
+    func: Function = fh.inner
+
+    results = []
+
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        # If the two operands of the xor instruction are the same, the LLIL will be translated to other instructions,
+        # e.g., <llil: eax = 0>, (LLIL_SET_REG). So we do not need to check whether the two operands are the same.
+        if il.operation == LowLevelILOperation.LLIL_XOR:
+            # Exclude cases related to the stack cookie
+            if is_nzxor_stack_cookie(fh.inner, bbh.inner[0], il):
+                return False
+            results.append((Characteristic("nzxor"), ih.address))
+            return False
+        else:
+            return True
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    yield from results
+
+
+def extract_insn_mnemonic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction mnemonic features"""
+    insn: DisassemblyInstruction = ih.inner
+    yield Mnemonic(insn.text[0].text), ih.address
+
+
+def extract_insn_obfs_call_plus_5_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse call $+5 instruction from the given instruction.
+    """
+    insn: DisassemblyInstruction = ih.inner
+    if insn.text[0].text == "call" and insn.text[2].text == "$+5" and insn.length == 5:
+        yield Characteristic("call $+5"), ih.address
+
+
+def extract_insn_peb_access_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction peb access
+
+    fs:[0x30] on x86, gs:[0x60] on x64
+    """
+    func: Function = fh.inner
+
+    results = []
+
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILOperation, index: int) -> bool:
+        if il.operation != LowLevelILOperation.LLIL_LOAD:
+            return True
+
+        src = il.src
+        if src.operation != LowLevelILOperation.LLIL_ADD:
+            return True
+
+        left = src.left
+        right = src.right
+
+        if left.operation != LowLevelILOperation.LLIL_REG:
+            return True
+
+        reg = left.src.name
+
+        if right.operation != LowLevelILOperation.LLIL_CONST:
+            return True
+
+        value = right.value.value
+        if (reg, value) not in (("fsbase", 0x30), ("gsbase", 0x60)):
+            return True
+
+        results.append((Characteristic("peb access"), ih.address))
+        return False
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    yield from results
+
+
+def extract_insn_segment_access_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction fs or gs access"""
+    func: Function = fh.inner
+
+    results = []
+
+    def llil_checker(il: LowLevelILInstruction, parent: LowLevelILInstruction, index: int) -> bool:
+        if il.operation == LowLevelILOperation.LLIL_REG:
+            reg = il.src.name
+            if reg == "fsbase":
+                results.append((Characteristic("fs access"), ih.address))
+                return False
+            elif reg == "gsbase":
+                results.append((Characteristic("gs access"), ih.address))
+                return False
+            return False
+
+        return True
+
+    for llil in func.get_llils_at(ih.address):
+        visit_llil_exprs(llil, llil_checker)
+
+    yield from results
+
+
+def extract_insn_cross_section_cflow(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """inspect the instruction for a CALL or JMP that crosses section boundaries"""
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+
+    if bv is None:
+        return
+
+    seg1 = bv.get_segment_at(ih.address)
+    sections1 = bv.get_sections_at(ih.address)
+    for ref in bv.get_code_refs_from(ih.address):
+        if len(bv.get_functions_at(ref)) == 0:
+            continue
+
+        seg2 = bv.get_segment_at(ref)
+        sections2 = bv.get_sections_at(ref)
+        if seg1 != seg2 or sections1 != sections2:
+            yield Characteristic("cross section flow"), ih.address
+
+
+def extract_function_calls_from(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract functions calls from features
+
+    most relevant at the function scope, however, its most efficient to extract at the instruction scope
+    """
+    func: Function = fh.inner
+    bv: BinaryView = func.view
+
+    if bv is None:
+        return
+
+    for il in func.get_llils_at(ih.address):
+        if il.operation not in [
+            LowLevelILOperation.LLIL_CALL,
+            LowLevelILOperation.LLIL_CALL_STACK_ADJUST,
+            LowLevelILOperation.LLIL_TAILCALL,
+        ]:
+            continue
+
+        dest = il.dest
+        if dest.operation == LowLevelILOperation.LLIL_CONST_PTR:
+            value = dest.value.value
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(value)
+        elif dest.operation == LowLevelILOperation.LLIL_CONST:
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(dest.value)
+        elif dest.operation == LowLevelILOperation.LLIL_LOAD:
+            indirect_src = dest.src
+            if indirect_src.operation == LowLevelILOperation.LLIL_CONST_PTR:
+                value = indirect_src.value.value
+                yield Characteristic("calls from"), AbsoluteVirtualAddress(value)
+            elif indirect_src.operation == LowLevelILOperation.LLIL_CONST:
+                yield Characteristic("calls from"), AbsoluteVirtualAddress(indirect_src.value)
+        elif dest.operation == LowLevelILOperation.LLIL_REG:
+            if dest.value.type in [
+                RegisterValueType.ImportedAddressValue,
+                RegisterValueType.ConstantValue,
+                RegisterValueType.ConstantPointerValue,
+            ]:
+                yield Characteristic("calls from"), AbsoluteVirtualAddress(dest.value.value)
+
+
+def extract_function_indirect_call_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """extract indirect function calls (e.g., call eax or call dword ptr [edx+4])
+    does not include calls like => call ds:dword_ABD4974
+
+    most relevant at the function or basic block scope;
+    however, its most efficient to extract at the instruction scope
+    """
+    func: Function = fh.inner
+
+    llil = func.get_llil_at(ih.address)
+    if llil is None or llil.operation not in [
+        LowLevelILOperation.LLIL_CALL,
+        LowLevelILOperation.LLIL_CALL_STACK_ADJUST,
+        LowLevelILOperation.LLIL_TAILCALL,
+    ]:
+        return
+
+    if llil.dest.operation in [LowLevelILOperation.LLIL_CONST, LowLevelILOperation.LLIL_CONST_PTR]:
+        return
+
+    if llil.dest.operation == LowLevelILOperation.LLIL_LOAD:
+        src = llil.dest.src
+        if src.operation in [LowLevelILOperation.LLIL_CONST, LowLevelILOperation.LLIL_CONST_PTR]:
+            return
+
+    yield Characteristic("indirect call"), ih.address
+
+
+def extract_features(f: FunctionHandle, bbh: BBHandle, insn: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract instruction features"""
+    for inst_handler in INSTRUCTION_HANDLERS:
+        for feature, ea in inst_handler(f, bbh, insn):
+            yield feature, ea
+
+
+INSTRUCTION_HANDLERS = (
+    extract_insn_api_features,
+    extract_insn_number_features,
+    extract_insn_bytes_features,
+    extract_insn_string_features,
+    extract_insn_offset_features,
+    extract_insn_nzxor_characteristic_features,
+    extract_insn_mnemonic_features,
+    extract_insn_obfs_call_plus_5_characteristic_features,
+    extract_insn_peb_access_characteristic_features,
+    extract_insn_cross_section_cflow,
+    extract_insn_segment_access_features,
+    extract_function_calls_from,
+    extract_function_indirect_call_characteristic_features,
+)

capa/features/extractors/common.py

@@ -0,0 +1,135 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import io
+import logging
+import binascii
+import contextlib
+from typing import Tuple, Iterator
+
+import pefile
+
+import capa.features
+import capa.features.extractors.elf
+import capa.features.extractors.pefile
+import capa.features.extractors.strings
+from capa.features.common import (
+    OS,
+    OS_ANY,
+    OS_AUTO,
+    ARCH_ANY,
+    FORMAT_PE,
+    FORMAT_ELF,
+    OS_WINDOWS,
+    FORMAT_FREEZE,
+    FORMAT_RESULT,
+    Arch,
+    Format,
+    String,
+    Feature,
+)
+from capa.features.freeze import is_freeze
+from capa.features.address import NO_ADDRESS, Address, FileOffsetAddress
+
+logger = logging.getLogger(__name__)
+
+# match strings for formats
+MATCH_PE = b"MZ"
+MATCH_ELF = b"\x7fELF"
+MATCH_RESULT = b'{"meta":'
+
+
+def extract_file_strings(buf, **kwargs) -> Iterator[Tuple[String, Address]]:
+    """
+    extract ASCII and UTF-16 LE strings from file
+    """
+    for s in capa.features.extractors.strings.extract_ascii_strings(buf):
+        yield String(s.s), FileOffsetAddress(s.offset)
+
+    for s in capa.features.extractors.strings.extract_unicode_strings(buf):
+        yield String(s.s), FileOffsetAddress(s.offset)
+
+
+def extract_format(buf) -> Iterator[Tuple[Feature, Address]]:
+    if buf.startswith(MATCH_PE):
+        yield Format(FORMAT_PE), NO_ADDRESS
+    elif buf.startswith(MATCH_ELF):
+        yield Format(FORMAT_ELF), NO_ADDRESS
+    elif is_freeze(buf):
+        yield Format(FORMAT_FREEZE), NO_ADDRESS
+    elif buf.startswith(MATCH_RESULT):
+        yield Format(FORMAT_RESULT), NO_ADDRESS
+    else:
+        # we likely end up here:
+        #  1. handling a file format (e.g. macho)
+        #
+        # for (1), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported file format: %s", binascii.hexlify(buf[:4]).decode("ascii"))
+        return
+
+
+def extract_arch(buf) -> Iterator[Tuple[Feature, Address]]:
+    if buf.startswith(MATCH_PE):
+        yield from capa.features.extractors.pefile.extract_file_arch(pe=pefile.PE(data=buf))
+
+    elif buf.startswith(MATCH_RESULT):
+        yield Arch(ARCH_ANY), NO_ADDRESS
+
+    elif buf.startswith(MATCH_ELF):
+        with contextlib.closing(io.BytesIO(buf)) as f:
+            arch = capa.features.extractors.elf.detect_elf_arch(f)
+
+        if arch not in capa.features.common.VALID_ARCH:
+            logger.debug("unsupported arch: %s", arch)
+            return
+
+        yield Arch(arch), NO_ADDRESS
+
+    else:
+        # we likely end up here:
+        #  1. handling shellcode, or
+        #  2. handling a new file format (e.g. macho)
+        #
+        # for (1) we can't do much - its shellcode and all bets are off.
+        # we could maybe accept a further CLI argument to specify the arch,
+        # but i think this would be rarely used.
+        # rules that rely on arch conditions will fail to match on shellcode.
+        #
+        # for (2), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported file format: %s, will not guess Arch", binascii.hexlify(buf[:4]).decode("ascii"))
+        return
+
+
+def extract_os(buf, os=OS_AUTO) -> Iterator[Tuple[Feature, Address]]:
+    if os != OS_AUTO:
+        yield OS(os), NO_ADDRESS
+
+    if buf.startswith(MATCH_PE):
+        yield OS(OS_WINDOWS), NO_ADDRESS
+    elif buf.startswith(MATCH_RESULT):
+        yield OS(OS_ANY), NO_ADDRESS
+    elif buf.startswith(MATCH_ELF):
+        with contextlib.closing(io.BytesIO(buf)) as f:
+            os = capa.features.extractors.elf.detect_elf_os(f)
+
+        if os not in capa.features.common.VALID_OS:
+            logger.debug("unsupported os: %s", os)
+            return
+
+        yield OS(os), NO_ADDRESS
+
+    else:
+        # we likely end up here:
+        #  1. handling shellcode, or
+        #  2. handling a new file format (e.g. macho)
+        #
+        # for (1) we can't do much - its shellcode and all bets are off.
+        # rules that rely on OS conditions will fail to match on shellcode.
+        #
+        # for (2), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported file format: %s, will not guess OS", binascii.hexlify(buf[:4]).decode("ascii"))
+        return

capa/features/extractors/dnfile/extractor.py

@@ -0,0 +1,155 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple, Union, Iterator, Optional
+from pathlib import Path
+
+import dnfile
+from dncil.cil.opcode import OpCodes
+
+import capa.features.extractors
+import capa.features.extractors.dotnetfile
+import capa.features.extractors.dnfile.file
+import capa.features.extractors.dnfile.insn
+import capa.features.extractors.dnfile.function
+from capa.features.common import Feature
+from capa.features.address import NO_ADDRESS, Address, DNTokenAddress, DNTokenOffsetAddress
+from capa.features.extractors.dnfile.types import DnType, DnUnmanagedMethod
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle, FeatureExtractor
+from capa.features.extractors.dnfile.helpers import (
+    get_dotnet_types,
+    get_dotnet_fields,
+    get_dotnet_managed_imports,
+    get_dotnet_managed_methods,
+    get_dotnet_unmanaged_imports,
+    get_dotnet_managed_method_bodies,
+)
+
+
+class DnFileFeatureExtractorCache:
+    def __init__(self, pe: dnfile.dnPE):
+        self.imports: Dict[int, Union[DnType, DnUnmanagedMethod]] = {}
+        self.native_imports: Dict[int, Union[DnType, DnUnmanagedMethod]] = {}
+        self.methods: Dict[int, Union[DnType, DnUnmanagedMethod]] = {}
+        self.fields: Dict[int, Union[DnType, DnUnmanagedMethod]] = {}
+        self.types: Dict[int, Union[DnType, DnUnmanagedMethod]] = {}
+
+        for import_ in get_dotnet_managed_imports(pe):
+            self.imports[import_.token] = import_
+        for native_import in get_dotnet_unmanaged_imports(pe):
+            self.native_imports[native_import.token] = native_import
+        for method in get_dotnet_managed_methods(pe):
+            self.methods[method.token] = method
+        for field in get_dotnet_fields(pe):
+            self.fields[field.token] = field
+        for type_ in get_dotnet_types(pe):
+            self.types[type_.token] = type_
+
+    def get_import(self, token: int) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+        return self.imports.get(token)
+
+    def get_native_import(self, token: int) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+        return self.native_imports.get(token)
+
+    def get_method(self, token: int) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+        return self.methods.get(token)
+
+    def get_field(self, token: int) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+        return self.fields.get(token)
+
+    def get_type(self, token: int) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+        return self.types.get(token)
+
+
+class DnfileFeatureExtractor(FeatureExtractor):
+    def __init__(self, path: Path):
+        super().__init__()
+        self.pe: dnfile.dnPE = dnfile.dnPE(str(path))
+
+        # pre-compute .NET token lookup tables; each .NET method has access to this cache for feature extraction
+        # most relevant at instruction scope
+        self.token_cache: DnFileFeatureExtractorCache = DnFileFeatureExtractorCache(self.pe)
+
+        # pre-compute these because we'll yield them at *every* scope.
+        self.global_features: List[Tuple[Feature, Address]] = []
+        self.global_features.extend(capa.features.extractors.dotnetfile.extract_file_format())
+        self.global_features.extend(capa.features.extractors.dotnetfile.extract_file_os(pe=self.pe))
+        self.global_features.extend(capa.features.extractors.dotnetfile.extract_file_arch(pe=self.pe))
+
+    def get_base_address(self):
+        return NO_ADDRESS
+
+    def extract_global_features(self):
+        yield from self.global_features
+
+    def extract_file_features(self):
+        yield from capa.features.extractors.dnfile.file.extract_features(self.pe)
+
+    def get_functions(self) -> Iterator[FunctionHandle]:
+        # create a method lookup table
+        methods: Dict[Address, FunctionHandle] = {}
+        for token, method in get_dotnet_managed_method_bodies(self.pe):
+            fh: FunctionHandle = FunctionHandle(
+                address=DNTokenAddress(token),
+                inner=method,
+                ctx={"pe": self.pe, "calls_from": set(), "calls_to": set(), "cache": self.token_cache},
+            )
+
+            # method tokens should be unique
+            assert fh.address not in methods.keys()
+            methods[fh.address] = fh
+
+        # calculate unique calls to/from each method
+        for fh in methods.values():
+            for insn in fh.inner.instructions:
+                if insn.opcode not in (
+                    OpCodes.Call,
+                    OpCodes.Callvirt,
+                    OpCodes.Jmp,
+                    OpCodes.Newobj,
+                ):
+                    continue
+
+                address: DNTokenAddress = DNTokenAddress(insn.operand.value)
+
+                # record call to destination method; note: we only consider MethodDef methods for destinations
+                dest: Optional[FunctionHandle] = methods.get(address)
+                if dest is not None:
+                    dest.ctx["calls_to"].add(fh.address)
+
+                # record call from source method; note: we record all unique calls from a MethodDef method, not just
+                # those calls to other MethodDef methods e.g. calls to imported MemberRef methods
+                fh.ctx["calls_from"].add(address)
+
+        yield from methods.values()
+
+    def extract_function_features(self, fh) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.dnfile.function.extract_features(fh)
+
+    def get_basic_blocks(self, f) -> Iterator[BBHandle]:
+        # each dotnet method is considered 1 basic block
+        yield BBHandle(
+            address=f.address,
+            inner=f.inner,
+        )
+
+    def extract_basic_block_features(self, fh, bbh):
+        # we don't support basic block features
+        yield from []
+
+    def get_instructions(self, fh, bbh):
+        for insn in bbh.inner.instructions:
+            yield InsnHandle(
+                address=DNTokenOffsetAddress(bbh.address, insn.offset - (fh.inner.offset + fh.inner.header_size)),
+                inner=insn,
+            )
+
+    def extract_insn_features(self, fh, bbh, ih) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.dnfile.insn.extract_features(fh, bbh, ih)

capa/features/extractors/dnfile/file.py

@@ -0,0 +1,63 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+from typing import Tuple, Iterator
+
+import dnfile
+
+import capa.features.extractors.dotnetfile
+from capa.features.file import Import, FunctionName
+from capa.features.common import Class, Format, String, Feature, Namespace, Characteristic
+from capa.features.address import Address
+
+
+def extract_file_import_names(pe: dnfile.dnPE) -> Iterator[Tuple[Import, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_import_names(pe=pe)
+
+
+def extract_file_format(pe: dnfile.dnPE) -> Iterator[Tuple[Format, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_format(pe=pe)
+
+
+def extract_file_function_names(pe: dnfile.dnPE) -> Iterator[Tuple[FunctionName, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_function_names(pe=pe)
+
+
+def extract_file_strings(pe: dnfile.dnPE) -> Iterator[Tuple[String, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_strings(pe=pe)
+
+
+def extract_file_mixed_mode_characteristic_features(pe: dnfile.dnPE) -> Iterator[Tuple[Characteristic, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_mixed_mode_characteristic_features(pe=pe)
+
+
+def extract_file_namespace_features(pe: dnfile.dnPE) -> Iterator[Tuple[Namespace, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_namespace_features(pe=pe)
+
+
+def extract_file_class_features(pe: dnfile.dnPE) -> Iterator[Tuple[Class, Address]]:
+    yield from capa.features.extractors.dotnetfile.extract_file_class_features(pe=pe)
+
+
+def extract_features(pe: dnfile.dnPE) -> Iterator[Tuple[Feature, Address]]:
+    for file_handler in FILE_HANDLERS:
+        for feature, address in file_handler(pe):
+            yield feature, address
+
+
+FILE_HANDLERS = (
+    extract_file_import_names,
+    extract_file_function_names,
+    extract_file_strings,
+    extract_file_format,
+    extract_file_mixed_mode_characteristic_features,
+    extract_file_namespace_features,
+    extract_file_class_features,
+)

capa/features/extractors/dnfile/function.py

@@ -0,0 +1,50 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+import logging
+from typing import Tuple, Iterator
+
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address
+from capa.features.extractors.base_extractor import FunctionHandle
+
+logger = logging.getLogger(__name__)
+
+
+def extract_function_calls_to(fh: FunctionHandle) -> Iterator[Tuple[Characteristic, Address]]:
+    """extract callers to a function"""
+    for dest in fh.ctx["calls_to"]:
+        yield Characteristic("calls to"), dest
+
+
+def extract_function_calls_from(fh: FunctionHandle) -> Iterator[Tuple[Characteristic, Address]]:
+    """extract callers from a function"""
+    for src in fh.ctx["calls_from"]:
+        yield Characteristic("calls from"), src
+
+
+def extract_recursive_call(fh: FunctionHandle) -> Iterator[Tuple[Characteristic, Address]]:
+    """extract recursive function call"""
+    if fh.address in fh.ctx["calls_to"]:
+        yield Characteristic("recursive call"), fh.address
+
+
+def extract_function_loop(fh: FunctionHandle) -> Iterator[Tuple[Characteristic, Address]]:
+    """extract loop indicators from a function"""
+    raise NotImplementedError()
+
+
+def extract_features(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+    for func_handler in FUNCTION_HANDLERS:
+        for feature, addr in func_handler(fh):
+            yield feature, addr
+
+
+FUNCTION_HANDLERS = (extract_function_calls_to, extract_function_calls_from, extract_recursive_call)

capa/features/extractors/dnfile/helpers.py

@@ -0,0 +1,335 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, Tuple, Union, Iterator, Optional
+
+import dnfile
+from dncil.cil.body import CilMethodBody
+from dncil.cil.error import MethodBodyFormatError
+from dncil.clr.token import Token, StringToken, InvalidToken
+from dncil.cil.body.reader import CilMethodBodyReaderBase
+
+from capa.features.common import FeatureAccess
+from capa.features.extractors.dnfile.types import DnType, DnUnmanagedMethod
+
+logger = logging.getLogger(__name__)
+
+
+class DnfileMethodBodyReader(CilMethodBodyReaderBase):
+    def __init__(self, pe: dnfile.dnPE, row: dnfile.mdtable.MethodDefRow):
+        self.pe: dnfile.dnPE = pe
+        self.offset: int = self.pe.get_offset_from_rva(row.Rva)
+
+    def read(self, n: int) -> bytes:
+        data: bytes = self.pe.get_data(self.pe.get_rva_from_offset(self.offset), n)
+        self.offset += n
+        return data
+
+    def tell(self) -> int:
+        return self.offset
+
+    def seek(self, offset: int) -> int:
+        self.offset = offset
+        return self.offset
+
+
+def resolve_dotnet_token(pe: dnfile.dnPE, token: Token) -> Union[dnfile.base.MDTableRow, InvalidToken, str]:
+    """map generic token to string or table row"""
+    assert pe.net is not None
+    assert pe.net.mdtables is not None
+
+    if isinstance(token, StringToken):
+        user_string: Optional[str] = read_dotnet_user_string(pe, token)
+        if user_string is None:
+            return InvalidToken(token.value)
+        return user_string
+
+    table: Optional[dnfile.base.ClrMetaDataTable] = pe.net.mdtables.tables.get(token.table)
+    if table is None:
+        # table index is not valid
+        return InvalidToken(token.value)
+
+    try:
+        return table.rows[token.rid - 1]
+    except IndexError:
+        # table index is valid but row index is not valid
+        return InvalidToken(token.value)
+
+
+def read_dotnet_method_body(pe: dnfile.dnPE, row: dnfile.mdtable.MethodDefRow) -> Optional[CilMethodBody]:
+    """read dotnet method body"""
+    try:
+        return CilMethodBody(DnfileMethodBodyReader(pe, row))
+    except MethodBodyFormatError as e:
+        logger.debug("failed to parse managed method body @ 0x%08x (%s)", row.Rva, e)
+        return None
+
+
+def read_dotnet_user_string(pe: dnfile.dnPE, token: StringToken) -> Optional[str]:
+    """read user string from #US stream"""
+    assert pe.net is not None
+
+    if pe.net.user_strings is None:
+        # stream may not exist (seen in obfuscated .NET)
+        logger.debug("#US stream does not exist for stream index 0x%08x", token.rid)
+        return None
+
+    try:
+        user_string: Optional[dnfile.stream.UserString] = pe.net.user_strings.get_us(token.rid)
+    except UnicodeDecodeError as e:
+        logger.debug("failed to decode #US stream index 0x%08x (%s)", token.rid, e)
+        return None
+
+    if user_string is None:
+        return None
+
+    return user_string.value
+
+
+def get_dotnet_managed_imports(pe: dnfile.dnPE) -> Iterator[DnType]:
+    """get managed imports from MemberRef table
+
+    see https://www.ntcore.com/files/dotnetformat.htm
+
+    10 - MemberRef Table
+        Each row represents an imported method
+            Class (index into the TypeRef, ModuleRef, MethodDef, TypeSpec or TypeDef tables)
+            Name (index into String heap)
+    01 - TypeRef Table
+        Each row represents an imported class, its namespace and the assembly which contains it
+            TypeName (index into String heap)
+            TypeNamespace (index into String heap)
+    """
+    for rid, member_ref in iter_dotnet_table(pe, dnfile.mdtable.MemberRef.number):
+        assert isinstance(member_ref, dnfile.mdtable.MemberRefRow)
+
+        if not isinstance(member_ref.Class.row, dnfile.mdtable.TypeRefRow):
+            # only process class imports from TypeRef table
+            continue
+
+        token: int = calculate_dotnet_token_value(dnfile.mdtable.MemberRef.number, rid)
+        access: Optional[str]
+
+        # assume .NET imports starting with get_/set_ are used to access a property
+        if member_ref.Name.startswith("get_"):
+            access = FeatureAccess.READ
+        elif member_ref.Name.startswith("set_"):
+            access = FeatureAccess.WRITE
+        else:
+            access = None
+
+        member_ref_name: str = member_ref.Name
+        if member_ref_name.startswith(("get_", "set_")):
+            # remove get_/set_ from MemberRef name
+            member_ref_name = member_ref_name[4:]
+
+        yield DnType(
+            token,
+            member_ref.Class.row.TypeName,
+            namespace=member_ref.Class.row.TypeNamespace,
+            member=member_ref_name,
+            access=access,
+        )
+
+
+def get_dotnet_methoddef_property_accessors(pe: dnfile.dnPE) -> Iterator[Tuple[int, str]]:
+    """get MethodDef methods used to access properties
+
+    see https://www.ntcore.com/files/dotnetformat.htm
+
+    24 - MethodSemantics Table
+        Links Events and Properties to specific methods. For example one Event can be associated to more methods. A property uses this table to associate get/set methods.
+            Semantics (a 2-byte bitmask of type MethodSemanticsAttributes)
+            Method (index into the MethodDef table)
+            Association (index into the Event or Property table; more precisely, a HasSemantics coded index)
+    """
+    for rid, method_semantics in iter_dotnet_table(pe, dnfile.mdtable.MethodSemantics.number):
+        assert isinstance(method_semantics, dnfile.mdtable.MethodSemanticsRow)
+
+        if method_semantics.Association.row is None:
+            logger.debug("MethodSemantics[0x%X] Association row is None", rid)
+            continue
+
+        if isinstance(method_semantics.Association.row, dnfile.mdtable.EventRow):
+            # ignore events
+            logger.debug("MethodSemantics[0x%X] ignoring Event", rid)
+            continue
+
+        if method_semantics.Method.table is None:
+            logger.debug("MethodSemantics[0x%X] Method table is None", rid)
+            continue
+
+        token: int = calculate_dotnet_token_value(
+            method_semantics.Method.table.number, method_semantics.Method.row_index
+        )
+
+        if method_semantics.Semantics.msSetter:
+            yield token, FeatureAccess.WRITE
+        elif method_semantics.Semantics.msGetter:
+            yield token, FeatureAccess.READ
+
+
+def get_dotnet_managed_methods(pe: dnfile.dnPE) -> Iterator[DnType]:
+    """get managed method names from TypeDef table
+
+    see https://www.ntcore.com/files/dotnetformat.htm
+
+    02 - TypeDef Table
+        Each row represents a class in the current assembly.
+            TypeName (index into String heap)
+            TypeNamespace (index into String heap)
+            MethodList (index into MethodDef table; it marks the first of a contiguous run of Methods owned by this Type)
+    """
+    accessor_map: Dict[int, str] = {}
+    for methoddef, methoddef_access in get_dotnet_methoddef_property_accessors(pe):
+        accessor_map[methoddef] = methoddef_access
+
+    for rid, typedef in iter_dotnet_table(pe, dnfile.mdtable.TypeDef.number):
+        assert isinstance(typedef, dnfile.mdtable.TypeDefRow)
+
+        for idx, method in enumerate(typedef.MethodList):
+            if method.table is None:
+                logger.debug("TypeDef[0x%X] MethodList[0x%X] table is None", rid, idx)
+                continue
+            if method.row is None:
+                logger.debug("TypeDef[0x%X] MethodList[0x%X] row is None", rid, idx)
+                continue
+
+            token: int = calculate_dotnet_token_value(method.table.number, method.row_index)
+            access: Optional[str] = accessor_map.get(token)
+
+            method_name: str = method.row.Name
+            if method_name.startswith(("get_", "set_")):
+                # remove get_/set_
+                method_name = method_name[4:]
+
+            yield DnType(token, typedef.TypeName, namespace=typedef.TypeNamespace, member=method_name, access=access)
+
+
+def get_dotnet_fields(pe: dnfile.dnPE) -> Iterator[DnType]:
+    """get fields from TypeDef table
+
+    see https://www.ntcore.com/files/dotnetformat.htm
+
+    02 - TypeDef Table
+        Each row represents a class in the current assembly.
+            TypeName (index into String heap)
+            TypeNamespace (index into String heap)
+            FieldList (index into Field table; it marks the first of a contiguous run of Fields owned by this Type)
+    """
+    for rid, typedef in iter_dotnet_table(pe, dnfile.mdtable.TypeDef.number):
+        assert isinstance(typedef, dnfile.mdtable.TypeDefRow)
+
+        for idx, field in enumerate(typedef.FieldList):
+            if field.table is None:
+                logger.debug("TypeDef[0x%X] FieldList[0x%X] table is None", rid, idx)
+                continue
+            if field.row is None:
+                logger.debug("TypeDef[0x%X] FieldList[0x%X] row is None", rid, idx)
+                continue
+            token: int = calculate_dotnet_token_value(field.table.number, field.row_index)
+            yield DnType(token, typedef.TypeName, namespace=typedef.TypeNamespace, member=field.row.Name)
+
+
+def get_dotnet_managed_method_bodies(pe: dnfile.dnPE) -> Iterator[Tuple[int, CilMethodBody]]:
+    """get managed methods from MethodDef table"""
+    for rid, method_def in iter_dotnet_table(pe, dnfile.mdtable.MethodDef.number):
+        assert isinstance(method_def, dnfile.mdtable.MethodDefRow)
+
+        if not method_def.ImplFlags.miIL or any((method_def.Flags.mdAbstract, method_def.Flags.mdPinvokeImpl)):
+            # skip methods that do not have a method body
+            continue
+
+        body: Optional[CilMethodBody] = read_dotnet_method_body(pe, method_def)
+        if body is None:
+            logger.debug("MethodDef[0x%X] method body is None", rid)
+            continue
+
+        token: int = calculate_dotnet_token_value(dnfile.mdtable.MethodDef.number, rid)
+        yield token, body
+
+
+def get_dotnet_unmanaged_imports(pe: dnfile.dnPE) -> Iterator[DnUnmanagedMethod]:
+    """get unmanaged imports from ImplMap table
+
+    see https://www.ntcore.com/files/dotnetformat.htm
+
+    28 - ImplMap Table
+        ImplMap table holds information about unmanaged methods that can be reached from managed code, using PInvoke dispatch
+            MemberForwarded (index into the Field or MethodDef table; more precisely, a MemberForwarded coded index)
+            ImportName (index into the String heap)
+            ImportScope (index into the ModuleRef table)
+    """
+    for rid, impl_map in iter_dotnet_table(pe, dnfile.mdtable.ImplMap.number):
+        assert isinstance(impl_map, dnfile.mdtable.ImplMapRow)
+
+        module: str
+        if impl_map.ImportScope.row is None:
+            logger.debug("ImplMap[0x%X] ImportScope row is None", rid)
+            module = ""
+        else:
+            module = impl_map.ImportScope.row.Name
+        method: str = impl_map.ImportName
+
+        member_forward_table: int
+        if impl_map.MemberForwarded.table is None:
+            logger.debug("ImplMap[0x%X] MemberForwarded table is None", rid)
+            continue
+        else:
+            member_forward_table = impl_map.MemberForwarded.table.number
+        member_forward_row: int = impl_map.MemberForwarded.row_index
+
+        # ECMA says "Each row of the ImplMap table associates a row in the MethodDef table (MemberForwarded) with the
+        # name of a routine (ImportName) in some unmanaged DLL (ImportScope)"; so we calculate and map the MemberForwarded
+        # MethodDef table token to help us later record native import method calls made from CIL
+        token: int = calculate_dotnet_token_value(member_forward_table, member_forward_row)
+
+        # like Kernel32.dll
+        if module and "." in module:
+            module = module.split(".")[0]
+
+        # like kernel32.CreateFileA
+        yield DnUnmanagedMethod(token, module, method)
+
+
+def get_dotnet_types(pe: dnfile.dnPE) -> Iterator[DnType]:
+    """get .NET types from TypeDef and TypeRef tables"""
+    for rid, typedef in iter_dotnet_table(pe, dnfile.mdtable.TypeDef.number):
+        assert isinstance(typedef, dnfile.mdtable.TypeDefRow)
+
+        typedef_token: int = calculate_dotnet_token_value(dnfile.mdtable.TypeDef.number, rid)
+        yield DnType(typedef_token, typedef.TypeName, namespace=typedef.TypeNamespace)
+
+    for rid, typeref in iter_dotnet_table(pe, dnfile.mdtable.TypeRef.number):
+        assert isinstance(typeref, dnfile.mdtable.TypeRefRow)
+
+        typeref_token: int = calculate_dotnet_token_value(dnfile.mdtable.TypeRef.number, rid)
+        yield DnType(typeref_token, typeref.TypeName, namespace=typeref.TypeNamespace)
+
+
+def calculate_dotnet_token_value(table: int, rid: int) -> int:
+    return ((table & 0xFF) << Token.TABLE_SHIFT) | (rid & Token.RID_MASK)
+
+
+def is_dotnet_mixed_mode(pe: dnfile.dnPE) -> bool:
+    assert pe.net is not None
+    assert pe.net.Flags is not None
+
+    return not bool(pe.net.Flags.CLR_ILONLY)
+
+
+def iter_dotnet_table(pe: dnfile.dnPE, table_index: int) -> Iterator[Tuple[int, dnfile.base.MDTableRow]]:
+    assert pe.net is not None
+    assert pe.net.mdtables is not None
+
+    for rid, row in enumerate(pe.net.mdtables.tables.get(table_index, [])):
+        # .NET tables are 1-indexed
+        yield rid + 1, row

capa/features/extractors/dnfile/insn.py

@@ -0,0 +1,227 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Tuple, Union, Iterator, Optional
+
+if TYPE_CHECKING:
+    from capa.features.extractors.dnfile.extractor import DnFileFeatureExtractorCache
+
+import dnfile
+from dncil.clr.token import Token, StringToken, InvalidToken
+from dncil.cil.opcode import OpCodes
+
+import capa.features.extractors.helpers
+from capa.features.insn import API, Number, Property
+from capa.features.common import Class, String, Feature, Namespace, FeatureAccess, Characteristic
+from capa.features.address import Address
+from capa.features.extractors.dnfile.types import DnType, DnUnmanagedMethod
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle
+from capa.features.extractors.dnfile.helpers import (
+    resolve_dotnet_token,
+    read_dotnet_user_string,
+    calculate_dotnet_token_value,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_callee(
+    pe: dnfile.dnPE, cache: DnFileFeatureExtractorCache, token: Token
+) -> Optional[Union[DnType, DnUnmanagedMethod]]:
+    """map .NET token to un/managed (generic) method"""
+    token_: int
+    if token.table == dnfile.mdtable.MethodSpec.number:
+        # map MethodSpec to MethodDef or MemberRef
+        row: Union[dnfile.base.MDTableRow, InvalidToken, str] = resolve_dotnet_token(pe, token)
+        assert isinstance(row, dnfile.mdtable.MethodSpecRow)
+
+        if row.Method.table is None:
+            logger.debug("MethodSpec[0x%X] Method table is None", token.rid)
+            return None
+
+        token_ = calculate_dotnet_token_value(row.Method.table.number, row.Method.row_index)
+    else:
+        token_ = token.value
+
+    callee: Optional[Union[DnType, DnUnmanagedMethod]] = cache.get_import(token_)
+    if callee is None:
+        # we must check unmanaged imports before managed methods because we map forwarded managed methods
+        # to their unmanaged imports; we prefer a forwarded managed method be mapped to its unmanaged import for analysis
+        callee = cache.get_native_import(token_)
+        if callee is None:
+            callee = cache.get_method(token_)
+    return callee
+
+
+def extract_insn_api_features(fh: FunctionHandle, bh, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction API features"""
+    if ih.inner.opcode not in (
+        OpCodes.Call,
+        OpCodes.Callvirt,
+        OpCodes.Jmp,
+        OpCodes.Newobj,
+    ):
+        return
+
+    callee: Optional[Union[DnType, DnUnmanagedMethod]] = get_callee(fh.ctx["pe"], fh.ctx["cache"], ih.inner.operand)
+    if isinstance(callee, DnType):
+        # ignore methods used to access properties
+        if callee.access is None:
+            # like System.IO.File::Delete
+            yield API(str(callee)), ih.address
+    elif isinstance(callee, DnUnmanagedMethod):
+        # like kernel32.CreateFileA
+        for name in capa.features.extractors.helpers.generate_symbols(callee.module, callee.method):
+            yield API(name), ih.address
+
+
+def extract_insn_property_features(fh: FunctionHandle, bh, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction property features"""
+    name: Optional[str] = None
+    access: Optional[str] = None
+
+    if ih.inner.opcode in (OpCodes.Call, OpCodes.Callvirt, OpCodes.Jmp):
+        # property access via MethodDef or MemberRef
+        callee: Optional[Union[DnType, DnUnmanagedMethod]] = get_callee(fh.ctx["pe"], fh.ctx["cache"], ih.inner.operand)
+        if isinstance(callee, DnType):
+            if callee.access is not None:
+                name = str(callee)
+                access = callee.access
+
+    elif ih.inner.opcode in (OpCodes.Ldfld, OpCodes.Ldflda, OpCodes.Ldsfld, OpCodes.Ldsflda):
+        # property read via Field
+        read_field: Optional[Union[DnType, DnUnmanagedMethod]] = fh.ctx["cache"].get_field(ih.inner.operand.value)
+        if read_field is not None:
+            name = str(read_field)
+            access = FeatureAccess.READ
+
+    elif ih.inner.opcode in (OpCodes.Stfld, OpCodes.Stsfld):
+        # property write via Field
+        write_field: Optional[Union[DnType, DnUnmanagedMethod]] = fh.ctx["cache"].get_field(ih.inner.operand.value)
+        if write_field is not None:
+            name = str(write_field)
+            access = FeatureAccess.WRITE
+
+    if name is not None:
+        if access is not None:
+            yield Property(name, access=access), ih.address
+        yield Property(name), ih.address
+
+
+def extract_insn_namespace_class_features(
+    fh: FunctionHandle, bh, ih: InsnHandle
+) -> Iterator[Tuple[Union[Namespace, Class], Address]]:
+    """parse instruction namespace and class features"""
+    type_: Optional[Union[DnType, DnUnmanagedMethod]] = None
+
+    if ih.inner.opcode in (
+        OpCodes.Call,
+        OpCodes.Callvirt,
+        OpCodes.Jmp,
+        OpCodes.Ldvirtftn,
+        OpCodes.Ldftn,
+        OpCodes.Newobj,
+    ):
+        # method call - includes managed methods (MethodDef, TypeRef) and properties (MethodSemantics, TypeRef)
+        type_ = get_callee(fh.ctx["pe"], fh.ctx["cache"], ih.inner.operand)
+
+    elif ih.inner.opcode in (
+        OpCodes.Ldfld,
+        OpCodes.Ldflda,
+        OpCodes.Ldsfld,
+        OpCodes.Ldsflda,
+        OpCodes.Stfld,
+        OpCodes.Stsfld,
+    ):
+        # field access
+        type_ = fh.ctx["cache"].get_field(ih.inner.operand.value)
+
+    # ECMA 335 VI.C.4.10
+    elif ih.inner.opcode in (
+        OpCodes.Initobj,
+        OpCodes.Box,
+        OpCodes.Castclass,
+        OpCodes.Cpobj,
+        OpCodes.Isinst,
+        OpCodes.Ldelem,
+        OpCodes.Ldelema,
+        OpCodes.Ldobj,
+        OpCodes.Mkrefany,
+        OpCodes.Newarr,
+        OpCodes.Refanyval,
+        OpCodes.Sizeof,
+        OpCodes.Stobj,
+        OpCodes.Unbox,
+        OpCodes.Constrained,
+        OpCodes.Stelem,
+        OpCodes.Unbox_Any,
+    ):
+        # type access
+        type_ = fh.ctx["cache"].get_type(ih.inner.operand.value)
+
+    if isinstance(type_, DnType):
+        yield Class(DnType.format_name(type_.class_, namespace=type_.namespace)), ih.address
+        if type_.namespace:
+            yield Namespace(type_.namespace), ih.address
+
+
+def extract_insn_number_features(fh, bh, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction number features"""
+    if ih.inner.is_ldc():
+        yield Number(ih.inner.get_ldc()), ih.address
+
+
+def extract_insn_string_features(fh: FunctionHandle, bh, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction string features"""
+    if not ih.inner.is_ldstr():
+        return
+
+    if not isinstance(ih.inner.operand, StringToken):
+        return
+
+    user_string: Optional[str] = read_dotnet_user_string(fh.ctx["pe"], ih.inner.operand)
+    if user_string is None:
+        return
+
+    if len(user_string) >= 4:
+        yield String(user_string), ih.address
+
+
+def extract_unmanaged_call_characteristic_features(
+    fh: FunctionHandle, bb: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Characteristic, Address]]:
+    if ih.inner.opcode not in (OpCodes.Call, OpCodes.Callvirt, OpCodes.Jmp):
+        return
+
+    row: Union[str, InvalidToken, dnfile.base.MDTableRow] = resolve_dotnet_token(fh.ctx["pe"], ih.inner.operand)
+    if not isinstance(row, dnfile.mdtable.MethodDefRow):
+        return
+
+    if any((row.Flags.mdPinvokeImpl, row.ImplFlags.miUnmanaged, row.ImplFlags.miNative)):
+        yield Characteristic("unmanaged call"), ih.address
+
+
+def extract_features(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract instruction features"""
+    for inst_handler in INSTRUCTION_HANDLERS:
+        for feature, addr in inst_handler(fh, bbh, ih):
+            assert isinstance(addr, Address)
+            yield feature, addr
+
+
+INSTRUCTION_HANDLERS = (
+    extract_insn_api_features,
+    extract_insn_property_features,
+    extract_insn_number_features,
+    extract_insn_string_features,
+    extract_insn_namespace_class_features,
+    extract_unmanaged_call_characteristic_features,
+)

capa/features/extractors/dnfile/types.py

@@ -0,0 +1,74 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from typing import Optional
+
+
+class DnType:
+    def __init__(self, token: int, class_: str, namespace: str = "", member: str = "", access: Optional[str] = None):
+        self.token: int = token
+        self.access: Optional[str] = access
+        self.namespace: str = namespace
+        self.class_: str = class_
+
+        if member == ".ctor":
+            member = "ctor"
+        if member == ".cctor":
+            member = "cctor"
+
+        self.member: str = member
+
+    def __hash__(self):
+        return hash((self.token, self.access, self.namespace, self.class_, self.member))
+
+    def __eq__(self, other):
+        return (
+            self.token == other.token
+            and self.access == other.access
+            and self.namespace == other.namespace
+            and self.class_ == other.class_
+            and self.member == other.member
+        )
+
+    def __str__(self):
+        return DnType.format_name(self.class_, namespace=self.namespace, member=self.member)
+
+    def __repr__(self):
+        return str(self)
+
+    @staticmethod
+    def format_name(class_: str, namespace: str = "", member: str = ""):
+        # like File::OpenRead
+        name: str = f"{class_}::{member}" if member else class_
+        if namespace:
+            # like System.IO.File::OpenRead
+            name = f"{namespace}.{name}"
+        return name
+
+
+class DnUnmanagedMethod:
+    def __init__(self, token: int, module: str, method: str):
+        self.token: int = token
+        self.module: str = module
+        self.method: str = method
+
+    def __hash__(self):
+        return hash((self.token, self.module, self.method))
+
+    def __eq__(self, other):
+        return self.token == other.token and self.module == other.module and self.method == other.method
+
+    def __str__(self):
+        return DnUnmanagedMethod.format_name(self.module, self.method)
+
+    def __repr__(self):
+        return str(self)
+
+    @staticmethod
+    def format_name(module, method):
+        return f"{module}.{method}"

capa/features/extractors/dnfile_.py

@@ -0,0 +1,158 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+from typing import Tuple, Iterator
+from pathlib import Path
+
+import dnfile
+import pefile
+
+from capa.features.common import (
+    OS,
+    OS_ANY,
+    ARCH_ANY,
+    ARCH_I386,
+    FORMAT_PE,
+    ARCH_AMD64,
+    FORMAT_DOTNET,
+    Arch,
+    Format,
+    Feature,
+)
+from capa.features.address import NO_ADDRESS, Address, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import FeatureExtractor
+
+logger = logging.getLogger(__name__)
+
+
+def extract_file_format(**kwargs) -> Iterator[Tuple[Feature, Address]]:
+    yield Format(FORMAT_PE), NO_ADDRESS
+    yield Format(FORMAT_DOTNET), NO_ADDRESS
+
+
+def extract_file_os(**kwargs) -> Iterator[Tuple[Feature, Address]]:
+    yield OS(OS_ANY), NO_ADDRESS
+
+
+def extract_file_arch(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[Feature, Address]]:
+    # to distinguish in more detail, see https://stackoverflow.com/a/23614024/10548020
+    # .NET 4.5 added option: any CPU, 32-bit preferred
+    assert pe.net is not None
+    assert pe.net.Flags is not None
+
+    if pe.net.Flags.CLR_32BITREQUIRED and pe.PE_TYPE == pefile.OPTIONAL_HEADER_MAGIC_PE:
+        yield Arch(ARCH_I386), NO_ADDRESS
+    elif not pe.net.Flags.CLR_32BITREQUIRED and pe.PE_TYPE == pefile.OPTIONAL_HEADER_MAGIC_PE_PLUS:
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+    else:
+        yield Arch(ARCH_ANY), NO_ADDRESS
+
+
+def extract_file_features(pe: dnfile.dnPE) -> Iterator[Tuple[Feature, Address]]:
+    for file_handler in FILE_HANDLERS:
+        for feature, address in file_handler(pe=pe):  # type: ignore
+            yield feature, address
+
+
+FILE_HANDLERS = (
+    # extract_file_export_names,
+    # extract_file_import_names,
+    # extract_file_section_names,
+    # extract_file_strings,
+    # extract_file_function_names,
+    extract_file_format,
+)
+
+
+def extract_global_features(pe: dnfile.dnPE) -> Iterator[Tuple[Feature, Address]]:
+    for handler in GLOBAL_HANDLERS:
+        for feature, addr in handler(pe=pe):  # type: ignore
+            yield feature, addr
+
+
+GLOBAL_HANDLERS = (
+    extract_file_os,
+    extract_file_arch,
+)
+
+
+class DnfileFeatureExtractor(FeatureExtractor):
+    def __init__(self, path: Path):
+        super().__init__()
+        self.path: Path = path
+        self.pe: dnfile.dnPE = dnfile.dnPE(str(path))
+
+    def get_base_address(self) -> AbsoluteVirtualAddress:
+        return AbsoluteVirtualAddress(0x0)
+
+    def get_entry_point(self) -> int:
+        # self.pe.net.Flags.CLT_NATIVE_ENTRYPOINT
+        #  True: native EP: Token
+        #  False: managed EP: RVA
+        assert self.pe.net is not None
+        assert self.pe.net.struct is not None
+
+        return self.pe.net.struct.EntryPointTokenOrRva
+
+    def extract_global_features(self):
+        yield from extract_global_features(self.pe)
+
+    def extract_file_features(self):
+        yield from extract_file_features(self.pe)
+
+    def is_dotnet_file(self) -> bool:
+        return bool(self.pe.net)
+
+    def is_mixed_mode(self) -> bool:
+        assert self.pe is not None
+        assert self.pe.net is not None
+        assert self.pe.net.Flags is not None
+
+        return not bool(self.pe.net.Flags.CLR_ILONLY)
+
+    def get_runtime_version(self) -> Tuple[int, int]:
+        assert self.pe is not None
+        assert self.pe.net is not None
+        assert self.pe.net.struct is not None
+
+        return self.pe.net.struct.MajorRuntimeVersion, self.pe.net.struct.MinorRuntimeVersion
+
+    def get_meta_version_string(self) -> str:
+        assert self.pe.net is not None
+        assert self.pe.net.metadata is not None
+        assert self.pe.net.metadata.struct is not None
+        assert self.pe.net.metadata.struct.Version is not None
+
+        vbuf = self.pe.net.metadata.struct.Version
+        assert isinstance(vbuf, bytes)
+
+        return vbuf.rstrip(b"\x00").decode("utf-8")
+
+    def get_functions(self):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def extract_function_features(self, f):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def get_basic_blocks(self, f):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def extract_basic_block_features(self, f, bb):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def get_instructions(self, f, bb):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def extract_insn_features(self, f, bb, insn):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def is_library_function(self, va):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")
+
+    def get_function_name(self, va):
+        raise NotImplementedError("DnfileFeatureExtractor can only be used to extract file features")

capa/features/extractors/dotnetfile.py

@@ -0,0 +1,239 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+from typing import Tuple, Iterator
+from pathlib import Path
+
+import dnfile
+import pefile
+
+import capa.features.extractors.helpers
+from capa.features.file import Import, FunctionName
+from capa.features.common import (
+    OS,
+    OS_ANY,
+    ARCH_ANY,
+    ARCH_I386,
+    FORMAT_PE,
+    ARCH_AMD64,
+    FORMAT_DOTNET,
+    Arch,
+    Class,
+    Format,
+    String,
+    Feature,
+    Namespace,
+    Characteristic,
+)
+from capa.features.address import NO_ADDRESS, Address, DNTokenAddress
+from capa.features.extractors.base_extractor import FeatureExtractor
+from capa.features.extractors.dnfile.helpers import (
+    DnType,
+    iter_dotnet_table,
+    is_dotnet_mixed_mode,
+    get_dotnet_managed_imports,
+    get_dotnet_managed_methods,
+    calculate_dotnet_token_value,
+    get_dotnet_unmanaged_imports,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def extract_file_format(**kwargs) -> Iterator[Tuple[Format, Address]]:
+    yield Format(FORMAT_PE), NO_ADDRESS
+    yield Format(FORMAT_DOTNET), NO_ADDRESS
+
+
+def extract_file_import_names(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[Import, Address]]:
+    for method in get_dotnet_managed_imports(pe):
+        # like System.IO.File::OpenRead
+        yield Import(str(method)), DNTokenAddress(method.token)
+
+    for imp in get_dotnet_unmanaged_imports(pe):
+        # like kernel32.CreateFileA
+        for name in capa.features.extractors.helpers.generate_symbols(imp.module, imp.method):
+            yield Import(name), DNTokenAddress(imp.token)
+
+
+def extract_file_function_names(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[FunctionName, Address]]:
+    for method in get_dotnet_managed_methods(pe):
+        yield FunctionName(str(method)), DNTokenAddress(method.token)
+
+
+def extract_file_namespace_features(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[Namespace, Address]]:
+    """emit namespace features from TypeRef and TypeDef tables"""
+
+    # namespaces may be referenced multiple times, so we need to filter
+    namespaces = set()
+
+    for _, typedef in iter_dotnet_table(pe, dnfile.mdtable.TypeDef.number):
+        # emit internal .NET namespaces
+        assert isinstance(typedef, dnfile.mdtable.TypeDefRow)
+        namespaces.add(typedef.TypeNamespace)
+
+    for _, typeref in iter_dotnet_table(pe, dnfile.mdtable.TypeRef.number):
+        # emit external .NET namespaces
+        assert isinstance(typeref, dnfile.mdtable.TypeRefRow)
+        namespaces.add(typeref.TypeNamespace)
+
+    # namespaces may be empty, discard
+    namespaces.discard("")
+
+    for namespace in namespaces:
+        # namespace do not have an associated token, so we yield 0x0
+        yield Namespace(namespace), NO_ADDRESS
+
+
+def extract_file_class_features(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[Class, Address]]:
+    """emit class features from TypeRef and TypeDef tables"""
+    for rid, typedef in iter_dotnet_table(pe, dnfile.mdtable.TypeDef.number):
+        # emit internal .NET classes
+        assert isinstance(typedef, dnfile.mdtable.TypeDefRow)
+
+        token = calculate_dotnet_token_value(dnfile.mdtable.TypeDef.number, rid)
+        yield Class(DnType.format_name(typedef.TypeName, namespace=typedef.TypeNamespace)), DNTokenAddress(token)
+
+    for rid, typeref in iter_dotnet_table(pe, dnfile.mdtable.TypeRef.number):
+        # emit external .NET classes
+        assert isinstance(typeref, dnfile.mdtable.TypeRefRow)
+
+        token = calculate_dotnet_token_value(dnfile.mdtable.TypeRef.number, rid)
+        yield Class(DnType.format_name(typeref.TypeName, namespace=typeref.TypeNamespace)), DNTokenAddress(token)
+
+
+def extract_file_os(**kwargs) -> Iterator[Tuple[OS, Address]]:
+    yield OS(OS_ANY), NO_ADDRESS
+
+
+def extract_file_arch(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[Arch, Address]]:
+    # to distinguish in more detail, see https://stackoverflow.com/a/23614024/10548020
+    # .NET 4.5 added option: any CPU, 32-bit preferred
+    assert pe.net is not None
+    assert pe.net.Flags is not None
+
+    if pe.net.Flags.CLR_32BITREQUIRED and pe.PE_TYPE == pefile.OPTIONAL_HEADER_MAGIC_PE:
+        yield Arch(ARCH_I386), NO_ADDRESS
+    elif not pe.net.Flags.CLR_32BITREQUIRED and pe.PE_TYPE == pefile.OPTIONAL_HEADER_MAGIC_PE_PLUS:
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+    else:
+        yield Arch(ARCH_ANY), NO_ADDRESS
+
+
+def extract_file_strings(pe: dnfile.dnPE, **kwargs) -> Iterator[Tuple[String, Address]]:
+    yield from capa.features.extractors.common.extract_file_strings(pe.__data__)
+
+
+def extract_file_mixed_mode_characteristic_features(
+    pe: dnfile.dnPE, **kwargs
+) -> Iterator[Tuple[Characteristic, Address]]:
+    if is_dotnet_mixed_mode(pe):
+        yield Characteristic("mixed mode"), NO_ADDRESS
+
+
+def extract_file_features(pe: dnfile.dnPE) -> Iterator[Tuple[Feature, Address]]:
+    for file_handler in FILE_HANDLERS:
+        for feature, addr in file_handler(pe=pe):  # type: ignore
+            yield feature, addr
+
+
+FILE_HANDLERS = (
+    extract_file_import_names,
+    extract_file_function_names,
+    extract_file_strings,
+    extract_file_format,
+    extract_file_mixed_mode_characteristic_features,
+    extract_file_namespace_features,
+    extract_file_class_features,
+)
+
+
+def extract_global_features(pe: dnfile.dnPE) -> Iterator[Tuple[Feature, Address]]:
+    for handler in GLOBAL_HANDLERS:
+        for feature, va in handler(pe=pe):  # type: ignore
+            yield feature, va
+
+
+GLOBAL_HANDLERS = (
+    extract_file_os,
+    extract_file_arch,
+)
+
+
+class DotnetFileFeatureExtractor(FeatureExtractor):
+    def __init__(self, path: Path):
+        super().__init__()
+        self.path: Path = path
+        self.pe: dnfile.dnPE = dnfile.dnPE(str(path))
+
+    def get_base_address(self):
+        return NO_ADDRESS
+
+    def get_entry_point(self) -> int:
+        # self.pe.net.Flags.CLT_NATIVE_ENTRYPOINT
+        #  True: native EP: Token
+        #  False: managed EP: RVA
+        assert self.pe.net is not None
+        assert self.pe.net.struct is not None
+
+        return self.pe.net.struct.EntryPointTokenOrRva
+
+    def extract_global_features(self):
+        yield from extract_global_features(self.pe)
+
+    def extract_file_features(self):
+        yield from extract_file_features(self.pe)
+
+    def is_dotnet_file(self) -> bool:
+        return bool(self.pe.net)
+
+    def is_mixed_mode(self) -> bool:
+        return is_dotnet_mixed_mode(self.pe)
+
+    def get_runtime_version(self) -> Tuple[int, int]:
+        assert self.pe.net is not None
+        assert self.pe.net.struct is not None
+        assert self.pe.net.struct.MajorRuntimeVersion is not None
+        assert self.pe.net.struct.MinorRuntimeVersion is not None
+
+        return self.pe.net.struct.MajorRuntimeVersion, self.pe.net.struct.MinorRuntimeVersion
+
+    def get_meta_version_string(self) -> str:
+        assert self.pe.net is not None
+        assert self.pe.net.metadata is not None
+        assert self.pe.net.metadata.struct is not None
+        assert self.pe.net.metadata.struct.Version is not None
+
+        vbuf = self.pe.net.metadata.struct.Version
+        assert isinstance(vbuf, bytes)
+
+        return vbuf.rstrip(b"\x00").decode("utf-8")
+
+    def get_functions(self):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def extract_function_features(self, f):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def get_basic_blocks(self, f):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def extract_basic_block_features(self, f, bb):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def get_instructions(self, f, bb):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def extract_insn_features(self, f, bb, insn):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def is_library_function(self, va):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")
+
+    def get_function_name(self, va):
+        raise NotImplementedError("DotnetFileFeatureExtractor can only be used to extract file features")

capa/features/extractors/elf.py

@@ -0,0 +1,985 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import struct
+import logging
+import itertools
+import collections
+from enum import Enum
+from typing import Set, Dict, List, Tuple, BinaryIO, Iterator, Optional
+from dataclasses import dataclass
+
+import Elf  # from vivisect
+
+logger = logging.getLogger(__name__)
+
+
+def align(v, alignment):
+    remainder = v % alignment
+    if remainder == 0:
+        return v
+    else:
+        return v + (alignment - remainder)
+
+
+def read_cstr(buf, offset) -> str:
+    s = buf[offset:]
+    s, _, _ = s.partition(b"\x00")
+    return s.decode("utf-8")
+
+
+class CorruptElfFile(ValueError):
+    pass
+
+
+class OS(str, Enum):
+    HPUX = "hpux"
+    NETBSD = "netbsd"
+    LINUX = "linux"
+    HURD = "hurd"
+    _86OPEN = "86open"
+    SOLARIS = "solaris"
+    AIX = "aix"
+    IRIX = "irix"
+    FREEBSD = "freebsd"
+    TRU64 = "tru64"
+    MODESTO = "modesto"
+    OPENBSD = "openbsd"
+    OPENVMS = "openvms"
+    NSK = "nsk"
+    AROS = "aros"
+    FENIXOS = "fenixos"
+    CLOUD = "cloud"
+    SYLLABLE = "syllable"
+    NACL = "nacl"
+    ANDROID = "android"
+
+
+# via readelf: https://github.com/bminor/binutils-gdb/blob/c0e94211e1ac05049a4ce7c192c9d14d1764eb3e/binutils/readelf.c#L19635-L19658
+# and here: https://github.com/bminor/binutils-gdb/blob/34c54daa337da9fadf87d2706d6a590ae1f88f4d/include/elf/common.h#L933-L939
+GNU_ABI_TAG = {
+    0: OS.LINUX,
+    1: OS.HURD,
+    2: OS.SOLARIS,
+    3: OS.FREEBSD,
+    4: OS.NETBSD,
+    5: OS.SYLLABLE,
+    6: OS.NACL,
+}
+
+
+@dataclass
+class Phdr:
+    type: int
+    offset: int
+    vaddr: int
+    paddr: int
+    filesz: int
+    buf: bytes
+
+
+@dataclass
+class Shdr:
+    name: int
+    type: int
+    flags: int
+    addr: int
+    offset: int
+    size: int
+    link: int
+    entsize: int
+    buf: bytes
+
+    @classmethod
+    def from_viv(cls, section, buf: bytes) -> "Shdr":
+        return cls(
+            section.sh_name,
+            section.sh_type,
+            section.sh_flags,
+            section.sh_addr,
+            section.sh_offset,
+            section.sh_size,
+            section.sh_link,
+            section.sh_entsize,
+            buf,
+        )
+
+
+class ELF:
+    def __init__(self, f: BinaryIO):
+        self.f = f
+
+        # these will all be initialized in `_parse()`
+        self.bitness: int
+        self.endian: str
+        self.e_phentsize: int
+        self.e_phnum: int
+        self.e_shentsize: int
+        self.e_shnum: int
+        self.phbuf: bytes
+        self.shbuf: bytes
+
+        self._parse()
+
+    def _parse(self):
+        self.f.seek(0x0)
+        self.file_header = self.f.read(0x40)
+
+        if not self.file_header.startswith(b"\x7fELF"):
+            raise CorruptElfFile("missing magic header")
+
+        ei_class, ei_data = struct.unpack_from("BB", self.file_header, 4)
+        logger.debug("ei_class: 0x%02x ei_data: 0x%02x", ei_class, ei_data)
+        if ei_class == 1:
+            self.bitness = 32
+        elif ei_class == 2:
+            self.bitness = 64
+        else:
+            raise CorruptElfFile(f"invalid ei_class: 0x{ei_class:02x}")
+
+        if ei_data == 1:
+            self.endian = "<"
+        elif ei_data == 2:
+            self.endian = ">"
+        else:
+            raise CorruptElfFile(f"not an ELF file: invalid ei_data: 0x{ei_data:02x}")
+
+        if self.bitness == 32:
+            e_phoff, e_shoff = struct.unpack_from(self.endian + "II", self.file_header, 0x1C)
+            self.e_phentsize, self.e_phnum = struct.unpack_from(self.endian + "HH", self.file_header, 0x2A)
+            self.e_shentsize, self.e_shnum = struct.unpack_from(self.endian + "HH", self.file_header, 0x2E)
+        elif self.bitness == 64:
+            e_phoff, e_shoff = struct.unpack_from(self.endian + "QQ", self.file_header, 0x20)
+            self.e_phentsize, self.e_phnum = struct.unpack_from(self.endian + "HH", self.file_header, 0x36)
+            self.e_shentsize, self.e_shnum = struct.unpack_from(self.endian + "HH", self.file_header, 0x3A)
+        else:
+            raise NotImplementedError()
+
+        logger.debug("e_phoff: 0x%02x e_phentsize: 0x%02x e_phnum: %d", e_phoff, self.e_phentsize, self.e_phnum)
+
+        self.f.seek(e_phoff)
+        program_header_size = self.e_phnum * self.e_phentsize
+        self.phbuf = self.f.read(program_header_size)
+        if len(self.phbuf) != program_header_size:
+            logger.warning("failed to read program headers")
+            self.e_phnum = 0
+
+        self.f.seek(e_shoff)
+        section_header_size = self.e_shnum * self.e_shentsize
+        self.shbuf = self.f.read(section_header_size)
+        if len(self.shbuf) != section_header_size:
+            logger.warning("failed to read section headers")
+            self.e_shnum = 0
+
+    OSABI = {
+        # via pyelftools: https://github.com/eliben/pyelftools/blob/0664de05ed2db3d39041e2d51d19622a8ef4fb0f/elftools/elf/enums.py#L35-L58
+        # some candidates are commented out because the are not useful values,
+        # at least when guessing OSes
+        # 0: "SYSV",  # too often used when OS is not SYSV
+        1: OS.HPUX,
+        2: OS.NETBSD,
+        3: OS.LINUX,
+        4: OS.HURD,
+        5: OS._86OPEN,
+        6: OS.SOLARIS,
+        7: OS.AIX,
+        8: OS.IRIX,
+        9: OS.FREEBSD,
+        10: OS.TRU64,
+        11: OS.MODESTO,
+        12: OS.OPENBSD,
+        13: OS.OPENVMS,
+        14: OS.NSK,
+        15: OS.AROS,
+        16: OS.FENIXOS,
+        17: OS.CLOUD,
+        # 53: "SORTFIX",      # i can't find any reference to this OS, i dont think it exists
+        # 64: "ARM_AEABI",    # not an OS
+        # 97: "ARM",          # not an OS
+        # 255: "STANDALONE",  # not an OS
+    }
+
+    @property
+    def ei_osabi(self) -> Optional[OS]:
+        (ei_osabi,) = struct.unpack_from(self.endian + "B", self.file_header, 7)
+        return ELF.OSABI.get(ei_osabi)
+
+    MACHINE = {
+        # via https://refspecs.linuxfoundation.org/elf/gabi4+/ch4.eheader.html
+        1: "M32",
+        2: "SPARC",
+        3: "i386",
+        4: "68K",
+        5: "88K",
+        6: "486",
+        7: "860",
+        8: "MIPS",
+        9: "S370",
+        10: "MIPS_RS3_LE",
+        11: "RS6000",
+        15: "PA_RISC",
+        16: "nCUBE",
+        17: "VPP500",
+        18: "SPARC32PLUS",
+        19: "960",
+        20: "PPC",
+        21: "PPC64",
+        22: "S390",
+        23: "SPU",
+        36: "V800",
+        37: "FR20",
+        38: "RH32",
+        39: "RCE",
+        40: "ARM",
+        41: "ALPHA",
+        42: "SH",
+        43: "SPARCV9",
+        44: "TRICORE",
+        45: "ARC",
+        46: "H8_300",
+        47: "H8_300H",
+        48: "H8S",
+        49: "H8_500",
+        50: "IA_64",
+        51: "MIPS_X",
+        52: "COLDFIRE",
+        53: "68HC12",
+        54: "MMA",
+        55: "PCP",
+        56: "NCPU",
+        57: "NDR1",
+        58: "STARCORE",
+        59: "ME16",
+        60: "ST100",
+        61: "TINYJ",
+        62: "amd64",
+        63: "PDSP",
+        64: "PDP10",
+        65: "PDP11",
+        66: "FX66",
+        67: "ST9PLUS",
+        68: "ST7",
+        69: "68HC16",
+        70: "68HC11",
+        71: "68HC08",
+        72: "68HC05",
+        73: "SVX",
+        74: "ST19",
+        75: "VAX",
+        76: "CRIS",
+        77: "JAVELIN",
+        78: "FIREPATH",
+        79: "ZSP",
+        80: "MMIX",
+        81: "HUANY",
+        82: "PRISM",
+        83: "AVR",
+        84: "FR30",
+        85: "D10V",
+        86: "D30V",
+        87: "V850",
+        88: "M32R",
+        89: "MN10300",
+        90: "MN10200",
+        91: "PJ",
+        92: "OPENRISC",
+        93: "ARC_A5",
+        94: "XTENSA",
+        95: "VIDEOCORE",
+        96: "TMM_GPP",
+        97: "NS32K",
+        98: "TPC",
+        99: "SNP1K",
+        100: "ST200",
+    }
+
+    @property
+    def e_machine(self) -> Optional[str]:
+        (e_machine,) = struct.unpack_from(self.endian + "H", self.file_header, 0x12)
+        return ELF.MACHINE.get(e_machine)
+
+    def parse_program_header(self, i) -> Phdr:
+        phent_offset = i * self.e_phentsize
+        phent = self.phbuf[phent_offset : phent_offset + self.e_phentsize]
+
+        (p_type,) = struct.unpack_from(self.endian + "I", phent, 0x0)
+        logger.debug("ph:p_type: 0x%04x", p_type)
+
+        if self.bitness == 32:
+            p_offset, p_vaddr, p_paddr, p_filesz = struct.unpack_from(self.endian + "IIII", phent, 0x4)
+        elif self.bitness == 64:
+            p_offset, p_vaddr, p_paddr, p_filesz = struct.unpack_from(self.endian + "QQQQ", phent, 0x8)
+        else:
+            raise NotImplementedError()
+
+        logger.debug("ph:p_offset: 0x%02x p_filesz: 0x%04x", p_offset, p_filesz)
+
+        self.f.seek(p_offset)
+        buf = self.f.read(p_filesz)
+        if len(buf) != p_filesz:
+            raise ValueError("failed to read program header content")
+
+        return Phdr(p_type, p_offset, p_vaddr, p_paddr, p_filesz, buf)
+
+    @property
+    def program_headers(self):
+        for i in range(self.e_phnum):
+            try:
+                yield self.parse_program_header(i)
+            except ValueError:
+                continue
+
+    def parse_section_header(self, i) -> Shdr:
+        shent_offset = i * self.e_shentsize
+        shent = self.shbuf[shent_offset : shent_offset + self.e_shentsize]
+
+        if self.bitness == 32:
+            sh_name, sh_type, sh_flags, sh_addr, sh_offset, sh_size, sh_link, _, _, sh_entsize = struct.unpack_from(
+                self.endian + "IIIIIIIIII", shent, 0x0
+            )
+        elif self.bitness == 64:
+            sh_name, sh_type, sh_flags, sh_addr, sh_offset, sh_size, sh_link, _, _, sh_entsize = struct.unpack_from(
+                self.endian + "IIQQQQIIQQ", shent, 0x0
+            )
+        else:
+            raise NotImplementedError()
+
+        logger.debug("sh:sh_offset: 0x%02x sh_size: 0x%04x", sh_offset, sh_size)
+
+        self.f.seek(sh_offset)
+        buf = self.f.read(sh_size)
+        if len(buf) != sh_size:
+            raise ValueError("failed to read section header content")
+
+        return Shdr(sh_name, sh_type, sh_flags, sh_addr, sh_offset, sh_size, sh_link, sh_entsize, buf)
+
+    @property
+    def section_headers(self):
+        for i in range(self.e_shnum):
+            try:
+                yield self.parse_section_header(i)
+            except ValueError:
+                continue
+
+    @property
+    def linker(self):
+        PT_INTERP = 0x3
+        for phdr in self.program_headers:
+            if phdr.type != PT_INTERP:
+                continue
+
+            return read_cstr(phdr.buf, 0)
+
+    @property
+    def versions_needed(self) -> Dict[str, Set[str]]:
+        # symbol version requirements are stored in the .gnu.version_r section,
+        # which has type SHT_GNU_verneed (0x6ffffffe).
+        #
+        # this contains a linked list of ElfXX_Verneed structs,
+        # each referencing a linked list of ElfXX_Vernaux structs.
+        # strings are stored in the section referenced by the sh_link field of the section header.
+        # each Verneed struct contains a reference to the name of the library,
+        # each Vernaux struct contains a reference to the name of a symbol.
+        SHT_GNU_VERNEED = 0x6FFFFFFE
+        for shdr in self.section_headers:
+            if shdr.type != SHT_GNU_VERNEED:
+                continue
+
+            # the linked section contains strings referenced by the verneed structures.
+            linked_shdr = self.parse_section_header(shdr.link)
+
+            versions_needed = collections.defaultdict(set)
+
+            # read verneed structures from the start of the section
+            # until the vn_next link is 0x0.
+            # each entry describes a shared object that is required by this binary.
+            vn_offset = 0x0
+            while True:
+                # ElfXX_Verneed layout is the same on 32 and 64 bit
+                vn_version, vn_cnt, vn_file, vn_aux, vn_next = struct.unpack_from(
+                    self.endian + "HHIII", shdr.buf, vn_offset
+                )
+                if vn_version != 1:
+                    # unexpected format, don't try to keep parsing
+                    break
+
+                # shared object names, like: "libdl.so.2"
+                so_name = read_cstr(linked_shdr.buf, vn_file)
+
+                # read vernaux structures linked from the verneed structure.
+                # there should be vn_cnt of these.
+                # each entry describes an ABI name required by the shared object.
+                vna_offset = vn_offset + vn_aux
+                for _ in range(vn_cnt):
+                    # ElfXX_Vernaux layout is the same on 32 and 64 bit
+                    _, _, _, vna_name, vna_next = struct.unpack_from(self.endian + "IHHII", shdr.buf, vna_offset)
+
+                    # ABI names, like: "GLIBC_2.2.5"
+                    abi = read_cstr(linked_shdr.buf, vna_name)
+                    versions_needed[so_name].add(abi)
+
+                    vna_offset += vna_next
+
+                vn_offset += vn_next
+                if vn_next == 0:
+                    break
+
+            return dict(versions_needed)
+
+        return {}
+
+    @property
+    def dynamic_entries(self) -> Iterator[Tuple[int, int]]:
+        """
+        read the entries from the dynamic section,
+        yielding the tag and value for each entry.
+        """
+        DT_NULL = 0x0
+        PT_DYNAMIC = 0x2
+        for phdr in self.program_headers:
+            if phdr.type != PT_DYNAMIC:
+                continue
+
+            offset = 0x0
+            while True:
+                if self.bitness == 32:
+                    d_tag, d_val = struct.unpack_from(self.endian + "II", phdr.buf, offset)
+                    offset += 8
+                elif self.bitness == 64:
+                    d_tag, d_val = struct.unpack_from(self.endian + "QQ", phdr.buf, offset)
+                    offset += 16
+                else:
+                    raise NotImplementedError()
+
+                if d_tag == DT_NULL:
+                    break
+
+                yield d_tag, d_val
+
+    @property
+    def strtab(self) -> Optional[bytes]:
+        """
+        fetch the bytes of the string table
+        referenced by the dynamic section.
+        """
+        DT_STRTAB = 0x5
+        DT_STRSZ = 0xA
+
+        strtab_addr = None
+        strtab_size = None
+
+        for d_tag, d_val in self.dynamic_entries:
+            if d_tag == DT_STRTAB:
+                strtab_addr = d_val
+                break
+
+        for d_tag, d_val in self.dynamic_entries:
+            if d_tag == DT_STRSZ:
+                strtab_size = d_val
+                break
+
+        if strtab_addr is None:
+            return None
+
+        if strtab_size is None:
+            return None
+
+        strtab_offset = None
+        for shdr in self.section_headers:
+            # the section header address should be defined
+            if shdr.addr and shdr.addr <= strtab_addr < shdr.addr + shdr.size:
+                strtab_offset = shdr.offset + (strtab_addr - shdr.addr)
+                break
+
+        if strtab_offset is None:
+            return None
+
+        self.f.seek(strtab_offset)
+        strtab_buf = self.f.read(strtab_size)
+
+        if len(strtab_buf) != strtab_size:
+            return None
+
+        return strtab_buf
+
+    @property
+    def needed(self) -> Iterator[str]:
+        """
+        read the names of DT_NEEDED entries from the dynamic section,
+        which correspond to dependencies on other shared objects,
+        like: `libpthread.so.0`
+        """
+        DT_NEEDED = 0x1
+        strtab = self.strtab
+        if not strtab:
+            return
+
+        for d_tag, d_val in self.dynamic_entries:
+            if d_tag != DT_NEEDED:
+                continue
+
+            try:
+                yield read_cstr(strtab, d_val)
+            except UnicodeDecodeError as e:
+                logger.warning("failed to read DT_NEEDED entry: %s", str(e))
+
+    @property
+    def symtab(self) -> Optional[Tuple[Shdr, Shdr]]:
+        """
+        fetch the Shdr for the symtab and the associated strtab.
+        """
+        SHT_SYMTAB = 0x2
+        for shdr in self.section_headers:
+            if shdr.type != SHT_SYMTAB:
+                continue
+
+            # the linked section contains strings referenced by the symtab structures.
+            strtab_shdr = self.parse_section_header(shdr.link)
+
+            return shdr, strtab_shdr
+
+        return None
+
+
+@dataclass
+class ABITag:
+    os: OS
+    kmajor: int
+    kminor: int
+    kpatch: int
+
+
+class PHNote:
+    def __init__(self, endian: str, buf: bytes):
+        self.endian = endian
+        self.buf = buf
+
+        # these will be initialized in `_parse()`
+        self.type_: int
+        self.descsz: int
+        self.name: str
+
+        self._parse()
+
+    def _parse(self):
+        namesz, self.descsz, self.type_ = struct.unpack_from(self.endian + "III", self.buf, 0x0)
+        name_offset = 0xC
+        self.desc_offset = name_offset + align(namesz, 0x4)
+
+        logger.debug("ph:namesz: 0x%02x descsz: 0x%02x type: 0x%04x", namesz, self.descsz, self.type_)
+
+        self.name = self.buf[name_offset : name_offset + namesz].partition(b"\x00")[0].decode("ascii")
+        logger.debug("name: %s", self.name)
+
+    @property
+    def abi_tag(self) -> Optional[ABITag]:
+        if self.type_ != 1:
+            # > The type field shall be 1.
+            # Linux Standard Base Specification 1.2
+            # ref: https://refspecs.linuxfoundation.org/LSB_1.2.0/gLSB/noteabitag.html
+            return None
+
+        if self.name != "GNU":
+            return None
+
+        if self.descsz < 16:
+            return None
+
+        desc = self.buf[self.desc_offset : self.desc_offset + self.descsz]
+        abi_tag, kmajor, kminor, kpatch = struct.unpack_from(self.endian + "IIII", desc, 0x0)
+        logger.debug("GNU_ABI_TAG: 0x%02x", abi_tag)
+
+        os = GNU_ABI_TAG.get(abi_tag)
+        if not os:
+            return None
+
+        logger.debug("abi tag: %s earliest compatible kernel: %d.%d.%d", os, kmajor, kminor, kpatch)
+
+        return ABITag(os, kmajor, kminor, kpatch)
+
+
+class SHNote:
+    def __init__(self, endian: str, buf: bytes):
+        self.endian = endian
+        self.buf = buf
+
+        # these will be initialized in `_parse()`
+        self.type_: int
+        self.descsz: int
+        self.name: str
+
+        self._parse()
+
+    def _parse(self):
+        namesz, self.descsz, self.type_ = struct.unpack_from(self.endian + "III", self.buf, 0x0)
+        name_offset = 0xC
+        self.desc_offset = name_offset + align(namesz, 0x4)
+
+        logger.debug("sh:namesz: 0x%02x descsz: 0x%02x type: 0x%04x", namesz, self.descsz, self.type_)
+
+        name_buf = self.buf[name_offset : name_offset + namesz]
+        self.name = read_cstr(name_buf, 0x0)
+        logger.debug("sh:name: %s", self.name)
+
+    @property
+    def abi_tag(self) -> Optional[ABITag]:
+        if self.name != "GNU":
+            return None
+
+        if self.descsz < 16:
+            return None
+
+        desc = self.buf[self.desc_offset : self.desc_offset + self.descsz]
+        abi_tag, kmajor, kminor, kpatch = struct.unpack_from(self.endian + "IIII", desc, 0x0)
+        logger.debug("GNU_ABI_TAG: 0x%02x", abi_tag)
+
+        os = GNU_ABI_TAG.get(abi_tag)
+        if not os:
+            return None
+
+        logger.debug("abi tag: %s earliest compatible kernel: %d.%d.%d", os, kmajor, kminor, kpatch)
+        return ABITag(os, kmajor, kminor, kpatch)
+
+
+@dataclass
+class Symbol:
+    name_offset: int
+    value: int
+    size: int
+    info: int
+    other: int
+    shndx: int
+
+
+class SymTab:
+    def __init__(
+        self,
+        endian: str,
+        bitness: int,
+        symtab: Shdr,
+        strtab: Shdr,
+    ) -> None:
+        self.symbols: List[Symbol] = []
+
+        self.symtab = symtab
+        self.strtab = strtab
+
+        self._parse(endian, bitness, symtab.buf)
+
+    def _parse(self, endian: str, bitness: int, symtab_buf: bytes) -> None:
+        """
+        return the symbol's information in
+        the order specified by sys/elf32.h
+        """
+        if self.symtab.entsize == 0:
+            return
+
+        for i in range(int(len(self.symtab.buf) / self.symtab.entsize)):
+            if bitness == 32:
+                name_offset, value, size, info, other, shndx = struct.unpack_from(
+                    endian + "IIIBBH", symtab_buf, i * self.symtab.entsize
+                )
+            elif bitness == 64:
+                name_offset, info, other, shndx, value, size = struct.unpack_from(
+                    endian + "IBBHQQ", symtab_buf, i * self.symtab.entsize
+                )
+
+            self.symbols.append(Symbol(name_offset, value, size, info, other, shndx))
+
+    def get_name(self, symbol: Symbol) -> str:
+        """
+        fetch a symbol's name from symtab's
+        associated strings' section (SHT_STRTAB)
+        """
+        if not self.strtab:
+            raise ValueError("no strings found")
+
+        for i in range(symbol.name_offset, self.strtab.size):
+            if self.strtab.buf[i] == 0:
+                return self.strtab.buf[symbol.name_offset : i].decode("utf-8")
+
+        raise ValueError("symbol name not found")
+
+    def get_symbols(self) -> Iterator[Symbol]:
+        """
+        return a tuple: (name, value, size, info, other, shndx)
+        for each symbol contained in the symbol table
+        """
+        yield from self.symbols
+
+    @classmethod
+    def from_viv(cls, elf: Elf.Elf) -> Optional["SymTab"]:
+        endian = "<" if elf.getEndian() == 0 else ">"
+        bitness = elf.bits
+
+        SHT_SYMTAB = 0x2
+        for section in elf.sections:
+            if section.sh_type == SHT_SYMTAB:
+                strtab_section = elf.sections[section.sh_link]
+                sh_symtab = Shdr.from_viv(section, elf.readAtOffset(section.sh_offset, section.sh_size))
+                sh_strtab = Shdr.from_viv(
+                    strtab_section, elf.readAtOffset(strtab_section.sh_offset, strtab_section.sh_size)
+                )
+
+        try:
+            return cls(endian, bitness, sh_symtab, sh_strtab)
+        except NameError:
+            return None
+        except Exception:
+            # all exceptions that could be encountered by
+            # cls._parse() imply a faulty symbol's table.
+            raise CorruptElfFile("malformed symbol's table")
+
+
+def guess_os_from_osabi(elf: ELF) -> Optional[OS]:
+    return elf.ei_osabi
+
+
+def guess_os_from_ph_notes(elf: ELF) -> Optional[OS]:
+    # search for PT_NOTE sections that specify an OS
+    # for example, on Linux there is a GNU section with minimum kernel version
+    PT_NOTE = 0x4
+    for phdr in elf.program_headers:
+        if phdr.type != PT_NOTE:
+            continue
+
+        note = PHNote(elf.endian, phdr.buf)
+
+        if note.type_ != 1:
+            # > The type field shall be 1.
+            # Linux Standard Base Specification 1.2
+            # ref: https://refspecs.linuxfoundation.org/LSB_1.2.0/gLSB/noteabitag.html
+            continue
+
+        if note.name == "Linux":
+            logger.debug("note owner: %s", "LINUX")
+            return OS.LINUX
+        elif note.name == "OpenBSD":
+            logger.debug("note owner: %s", "OPENBSD")
+            return OS.OPENBSD
+        elif note.name == "NetBSD":
+            logger.debug("note owner: %s", "NETBSD")
+            return OS.NETBSD
+        elif note.name == "FreeBSD":
+            logger.debug("note owner: %s", "FREEBSD")
+            return OS.FREEBSD
+        elif note.name == "Android":
+            logger.debug("note owner: %s", "Android")
+            # see the following for parsing the structure:
+            # https://android.googlesource.com/platform/ndk/+/master/parse_elfnote.py
+            return OS.ANDROID
+        elif note.name == "GNU":
+            abi_tag = note.abi_tag
+            if abi_tag:
+                return abi_tag.os
+            else:
+                # cannot make a guess about the OS, but probably linux or hurd
+                pass
+
+    return None
+
+
+def guess_os_from_sh_notes(elf: ELF) -> Optional[OS]:
+    # search for notes stored in sections that aren't visible in program headers.
+    # e.g. .note.Linux in Linux kernel modules.
+    SHT_NOTE = 0x7
+    for shdr in elf.section_headers:
+        if shdr.type != SHT_NOTE:
+            continue
+
+        note = SHNote(elf.endian, shdr.buf)
+
+        if note.name == "Linux":
+            logger.debug("note owner: %s", "LINUX")
+            return OS.LINUX
+        elif note.name == "OpenBSD":
+            logger.debug("note owner: %s", "OPENBSD")
+            return OS.OPENBSD
+        elif note.name == "NetBSD":
+            logger.debug("note owner: %s", "NETBSD")
+            return OS.NETBSD
+        elif note.name == "FreeBSD":
+            logger.debug("note owner: %s", "FREEBSD")
+            return OS.FREEBSD
+        elif note.name == "GNU":
+            abi_tag = note.abi_tag
+            if abi_tag:
+                return abi_tag.os
+            else:
+                # cannot make a guess about the OS, but probably linux or hurd
+                pass
+
+    return None
+
+
+def guess_os_from_linker(elf: ELF) -> Optional[OS]:
+    # search for recognizable dynamic linkers (interpreters)
+    # for example, on linux, we see file paths like: /lib64/ld-linux-x86-64.so.2
+    linker = elf.linker
+    if linker and "ld-linux" in elf.linker:
+        return OS.LINUX
+
+    return None
+
+
+def guess_os_from_abi_versions_needed(elf: ELF) -> Optional[OS]:
+    # then lets look for GLIBC symbol versioning requirements.
+    # this will let us guess about linux/hurd in some cases.
+
+    versions_needed = elf.versions_needed
+    if any(abi.startswith("GLIBC") for abi in itertools.chain(*versions_needed.values())):
+        # there are any GLIBC versions needed
+
+        if elf.e_machine != "i386":
+            # GLIBC runs on Linux and Hurd.
+            # for Hurd, its *only* on i386.
+            # so if we're not on i386, then we're on Linux.
+            return OS.LINUX
+
+        else:
+            # we're on i386, so we could be on either Linux or Hurd.
+            linker = elf.linker
+
+            if linker and "ld-linux" in linker:
+                return OS.LINUX
+
+            elif linker and "/ld.so" in linker:
+                return OS.HURD
+
+            else:
+                # we don't have any good guesses based on versions needed
+                pass
+
+    return None
+
+
+def guess_os_from_needed_dependencies(elf: ELF) -> Optional[OS]:
+    for needed in elf.needed:
+        if needed.startswith("libmachuser.so"):
+            return OS.HURD
+        if needed.startswith("libhurduser.so"):
+            return OS.HURD
+        if needed.startswith("libandroid.so"):
+            return OS.ANDROID
+
+    return None
+
+
+def guess_os_from_symtab(elf: ELF) -> Optional[OS]:
+    shdrs = elf.symtab
+    if not shdrs:
+        # executable does not contain a symbol table
+        # or the symbol's names are stripped
+        return None
+
+    symtab_shdr, strtab_shdr = shdrs
+    symtab = SymTab(elf.endian, elf.bitness, symtab_shdr, strtab_shdr)
+
+    keywords = {
+        OS.LINUX: [
+            "linux",
+            "/linux/",
+        ],
+    }
+
+    for symbol in symtab.get_symbols():
+        sym_name = symtab.get_name(symbol)
+
+        for os, hints in keywords.items():
+            if any(hint in sym_name for hint in hints):
+                return os
+
+    return None
+
+
+def detect_elf_os(f) -> str:
+    """
+    f: type Union[BinaryIO, IDAIO]
+    """
+    try:
+        elf = ELF(f)
+    except Exception as e:
+        logger.warning("Error parsing ELF file: %s", e)
+        return "unknown"
+
+    try:
+        osabi_guess = guess_os_from_osabi(elf)
+        logger.debug("guess: osabi: %s", osabi_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from OSABI: %s", e)
+        osabi_guess = None
+
+    try:
+        ph_notes_guess = guess_os_from_ph_notes(elf)
+        logger.debug("guess: ph notes: %s", ph_notes_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from program header notes: %s", e)
+        ph_notes_guess = None
+
+    try:
+        sh_notes_guess = guess_os_from_sh_notes(elf)
+        logger.debug("guess: sh notes: %s", sh_notes_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from section header notes: %s", e)
+        sh_notes_guess = None
+
+    try:
+        linker_guess = guess_os_from_linker(elf)
+        logger.debug("guess: linker: %s", linker_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from linker: %s", e)
+        linker_guess = None
+
+    try:
+        abi_versions_needed_guess = guess_os_from_abi_versions_needed(elf)
+        logger.debug("guess: ABI versions needed: %s", abi_versions_needed_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from ABI versions needed: %s", e)
+        abi_versions_needed_guess = None
+
+    try:
+        needed_dependencies_guess = guess_os_from_needed_dependencies(elf)
+        logger.debug("guess: needed dependencies: %s", needed_dependencies_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from needed dependencies: %s", e)
+        needed_dependencies_guess = None
+
+    try:
+        symtab_guess = guess_os_from_symtab(elf)
+        logger.debug("guess: pertinent symbol name: %s", symtab_guess)
+    except Exception as e:
+        logger.warning("Error guessing OS from symbol table: %s", e)
+        symtab_guess = None
+
+    ret = None
+
+    if osabi_guess:
+        ret = osabi_guess
+
+    elif ph_notes_guess:
+        ret = ph_notes_guess
+
+    elif sh_notes_guess:
+        ret = sh_notes_guess
+
+    elif linker_guess:
+        ret = linker_guess
+
+    elif abi_versions_needed_guess:
+        ret = abi_versions_needed_guess
+
+    elif needed_dependencies_guess:
+        ret = needed_dependencies_guess
+
+    elif symtab_guess:
+        ret = symtab_guess
+
+    return ret.value if ret is not None else "unknown"
+
+
+def detect_elf_arch(f: BinaryIO) -> str:
+    return ELF(f).e_machine or "unknown"

capa/features/extractors/elffile.py

@@ -0,0 +1,203 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import io
+import logging
+from typing import Tuple, Iterator
+from pathlib import Path
+
+from elftools.elf.elffile import ELFFile, SymbolTableSection
+from elftools.elf.relocation import RelocationSection
+
+import capa.features.extractors.common
+from capa.features.file import Export, Import, Section
+from capa.features.common import OS, FORMAT_ELF, Arch, Format, Feature
+from capa.features.address import NO_ADDRESS, FileOffsetAddress, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import FeatureExtractor
+
+logger = logging.getLogger(__name__)
+
+
+def extract_file_export_names(elf: ELFFile, **kwargs):
+    for section in elf.iter_sections():
+        if not isinstance(section, SymbolTableSection):
+            continue
+
+        if section["sh_entsize"] == 0:
+            logger.debug("Symbol table '%s' has a sh_entsize of zero!", section.name)
+            continue
+
+        logger.debug("Symbol table '%s' contains %s entries:", section.name, section.num_symbols())
+
+        for symbol in section.iter_symbols():
+            # The following conditions are based on the following article
+            # http://www.m4b.io/elf/export/binary/analysis/2015/05/25/what-is-an-elf-export.html
+            if not symbol.name:
+                continue
+            if symbol.entry.st_info.type not in ["STT_FUNC", "STT_OBJECT", "STT_IFUNC"]:
+                continue
+            if symbol.entry.st_value == 0:
+                continue
+            if symbol.entry.st_shndx == "SHN_UNDEF":
+                continue
+
+            yield Export(symbol.name), AbsoluteVirtualAddress(symbol.entry.st_value)
+
+
+def extract_file_import_names(elf: ELFFile, **kwargs):
+    # Create a dictionary to store symbol names by their index
+    symbol_names = {}
+
+    # Extract symbol names and store them in the dictionary
+    for section in elf.iter_sections():
+        if not isinstance(section, SymbolTableSection):
+            continue
+
+        for _, symbol in enumerate(section.iter_symbols()):
+            # The following conditions are based on the following article
+            # http://www.m4b.io/elf/export/binary/analysis/2015/05/25/what-is-an-elf-export.html
+            if not symbol.name:
+                continue
+            if symbol.entry.st_info.type not in ["STT_FUNC", "STT_OBJECT", "STT_IFUNC"]:
+                continue
+            if symbol.entry.st_value != 0:
+                continue
+            if symbol.entry.st_shndx != "SHN_UNDEF":
+                continue
+            if symbol.entry.st_name == 0:
+                continue
+
+            symbol_names[_] = symbol.name
+
+    for section in elf.iter_sections():
+        if not isinstance(section, RelocationSection):
+            continue
+
+        if section["sh_entsize"] == 0:
+            logger.debug("Symbol table '%s' has a sh_entsize of zero!", section.name)
+            continue
+
+        logger.debug("Symbol table '%s' contains %s entries:", section.name, section.num_relocations())
+
+        for relocation in section.iter_relocations():
+            # Extract the symbol name from the symbol table using the symbol index in the relocation
+            if relocation["r_info_sym"] not in symbol_names:
+                continue
+            yield Import(symbol_names[relocation["r_info_sym"]]), FileOffsetAddress(relocation["r_offset"])
+
+
+def extract_file_section_names(elf: ELFFile, **kwargs):
+    for section in elf.iter_sections():
+        if section.name:
+            yield Section(section.name), AbsoluteVirtualAddress(section.header.sh_addr)
+        elif section.is_null():
+            yield Section("NULL"), AbsoluteVirtualAddress(section.header.sh_addr)
+
+
+def extract_file_strings(buf, **kwargs):
+    yield from capa.features.extractors.common.extract_file_strings(buf)
+
+
+def extract_file_os(elf: ELFFile, buf, **kwargs):
+    # our current approach does not always get an OS value, e.g. for packed samples
+    # for file limitation purposes, we're more lax here
+    try:
+        os_tuple = next(capa.features.extractors.common.extract_os(buf))
+        yield os_tuple
+    except StopIteration:
+        yield OS("unknown"), NO_ADDRESS
+
+
+def extract_file_format(**kwargs):
+    yield Format(FORMAT_ELF), NO_ADDRESS
+
+
+def extract_file_arch(elf: ELFFile, **kwargs):
+    arch = elf.get_machine_arch()
+    if arch == "x86":
+        yield Arch("i386"), NO_ADDRESS
+    elif arch == "x64":
+        yield Arch("amd64"), NO_ADDRESS
+    else:
+        logger.warning("unsupported architecture: %s", arch)
+
+
+def extract_file_features(elf: ELFFile, buf: bytes) -> Iterator[Tuple[Feature, int]]:
+    for file_handler in FILE_HANDLERS:
+        for feature, addr in file_handler(elf=elf, buf=buf):  # type: ignore
+            yield feature, addr
+
+
+FILE_HANDLERS = (
+    extract_file_export_names,
+    extract_file_import_names,
+    extract_file_section_names,
+    extract_file_strings,
+    # no library matching
+    extract_file_format,
+)
+
+
+def extract_global_features(elf: ELFFile, buf: bytes) -> Iterator[Tuple[Feature, int]]:
+    for global_handler in GLOBAL_HANDLERS:
+        for feature, addr in global_handler(elf=elf, buf=buf):  # type: ignore
+            yield feature, addr
+
+
+GLOBAL_HANDLERS = (
+    extract_file_os,
+    extract_file_arch,
+)
+
+
+class ElfFeatureExtractor(FeatureExtractor):
+    def __init__(self, path: Path):
+        super().__init__()
+        self.path: Path = path
+        self.elf = ELFFile(io.BytesIO(path.read_bytes()))
+
+    def get_base_address(self):
+        # virtual address of the first segment with type LOAD
+        for segment in self.elf.iter_segments():
+            if segment.header.p_type == "PT_LOAD":
+                return AbsoluteVirtualAddress(segment.header.p_vaddr)
+
+    def extract_global_features(self):
+        buf = self.path.read_bytes()
+
+        for feature, addr in extract_global_features(self.elf, buf):
+            yield feature, addr
+
+    def extract_file_features(self):
+        buf = self.path.read_bytes()
+
+        for feature, addr in extract_file_features(self.elf, buf):
+            yield feature, addr
+
+    def get_functions(self):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def extract_function_features(self, f):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def get_basic_blocks(self, f):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def extract_basic_block_features(self, f, bb):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def get_instructions(self, f, bb):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def extract_insn_features(self, f, bb, insn):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def is_library_function(self, addr):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")
+
+    def get_function_name(self, addr):
+        raise NotImplementedError("ElfFeatureExtractor can only be used to extract file features")

capa/features/extractors/helpers.py

@@ -1,39 +1,49 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-import sys
+import struct
 import builtins
-
-from capa.features.insn import API
+from typing import Tuple, Iterator
 
 MIN_STACKSTRING_LEN = 8
 
 
-def xor_static(data, i):
-    if sys.version_info >= (3, 0):
-        return bytes(c ^ i for c in data)
-    else:
-        return "".join(chr(ord(c) ^ i) for c in data)
+def xor_static(data: bytes, i: int) -> bytes:
+    return bytes(c ^ i for c in data)
 
 
-def is_aw_function(function_name):
+def is_aw_function(symbol: str) -> bool:
     """
     is the given function name an A/W function?
     these are variants of functions that, on Windows, accept either a narrow or wide string.
     """
-    if len(function_name) < 2:
+    if len(symbol) < 2:
         return False
 
     # last character should be 'A' or 'W'
-    if function_name[-1] not in ("A", "W"):
+    if symbol[-1] not in ("A", "W"):
         return False
 
-    # second to last character should be lowercase letter
-    return "a" <= function_name[-2] <= "z" or "0" <= function_name[-2] <= "9"
+    return True
 
 
-def generate_api_features(apiname, va):
+def is_ordinal(symbol: str) -> bool:
     """
-    for a given function name and address, generate API names.
+    is the given symbol an ordinal that is prefixed by "#"?
+    """
+    if symbol:
+        return symbol[0] == "#"
+    return False
+
+
+def generate_symbols(dll: str, symbol: str) -> Iterator[str]:
+    """
+    for a given dll and symbol name, generate variants.
     we over-generate features to make matching easier.
     these include:
       - kernel32.CreateFileA
@@ -41,23 +51,101 @@ def generate_api_features(apiname, va):
       - CreateFileA
       - CreateFile
     """
-    # (kernel32.CreateFileA, 0x401000)
-    yield API(apiname), va
+    # normalize dll name
+    dll = dll.lower()
 
-    if is_aw_function(apiname):
-        # (kernel32.CreateFile, 0x401000)
-        yield API(apiname[:-1]), va
+    # kernel32.CreateFileA
+    yield f"{dll}.{symbol}"
 
-    if "." in apiname:
-        modname, impname = apiname.split(".")
-        # strip modname to support importname-only matching
-        # (CreateFileA, 0x401000)
-        yield API(impname), va
+    if not is_ordinal(symbol):
+        # CreateFileA
+        yield symbol
 
-        if is_aw_function(impname):
-            # (CreateFile, 0x401000)
-            yield API(impname[:-1]), va
+    if is_aw_function(symbol):
+        # kernel32.CreateFile
+        yield f"{dll}.{symbol[:-1]}"
+
+        if not is_ordinal(symbol):
+            # CreateFile
+            yield symbol[:-1]
 
 
-def all_zeros(bytez):
+def reformat_forwarded_export_name(forwarded_name: str) -> str:
+    """
+    a forwarded export has a DLL name/path an symbol name.
+    we want the former to be lowercase, and the latter to be verbatim.
+    """
+
+    # use rpartition so we can split on separator between dll and name.
+    # the dll name can be a full path, like in the case of
+    # ef64d6d7c34250af8e21a10feb931c9b
+    # which i assume means the path can have embedded periods.
+    # so we don't want the first period, we want the last.
+    forwarded_dll, _, forwarded_symbol = forwarded_name.rpartition(".")
+    forwarded_dll = forwarded_dll.lower()
+
+    return f"{forwarded_dll}.{forwarded_symbol}"
+
+
+def all_zeros(bytez: bytes) -> bool:
     return all(b == 0 for b in builtins.bytes(bytez))
+
+
+def twos_complement(val: int, bits: int) -> int:
+    """
+    compute the 2's complement of int value val
+
+    from: https://stackoverflow.com/a/9147327/87207
+    """
+    # if sign bit is set e.g., 8bit: 128-255
+    if (val & (1 << (bits - 1))) != 0:
+        # compute negative value
+        return val - (1 << bits)
+    else:
+        # return positive value as is
+        return val
+
+
+def carve_pe(pbytes: bytes, offset: int = 0) -> Iterator[Tuple[int, int]]:
+    """
+    Generate (offset, key) tuples of embedded PEs
+
+    Based on the version from vivisect:
+      https://github.com/vivisect/vivisect/blob/7be4037b1cecc4551b397f840405a1fc606f9b53/PE/carve.py#L19
+    And its IDA adaptation:
+      capa/features/extractors/ida/file.py
+    """
+    mz_xor = [
+        (
+            xor_static(b"MZ", key),
+            xor_static(b"PE", key),
+            key,
+        )
+        for key in range(256)
+    ]
+
+    pblen = len(pbytes)
+    todo = [(pbytes.find(mzx, offset), mzx, pex, key) for mzx, pex, key in mz_xor]
+    todo = [(off, mzx, pex, key) for (off, mzx, pex, key) in todo if off != -1]
+
+    while len(todo):
+        off, mzx, pex, key = todo.pop()
+
+        # The MZ header has one field we will check
+        # e_lfanew is at 0x3c
+        e_lfanew = off + 0x3C
+        if pblen < (e_lfanew + 4):
+            continue
+
+        newoff = struct.unpack("<I", xor_static(pbytes[e_lfanew : e_lfanew + 4], key))[0]
+
+        nextres = pbytes.find(mzx, off + 1)
+        if nextres != -1:
+            todo.append((nextres, mzx, pex, key))
+
+        peoff = off + newoff
+        if pblen < (peoff + 2):
+            continue
+
+        if pbytes[peoff : peoff + 2] == pex:
+            yield (off, key)

capa/features/extractors/ida/__init__.py

@@ -1,76 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import sys
-import types
-
-import idaapi
-
-import capa.features.extractors.ida.file
-import capa.features.extractors.ida.insn
-import capa.features.extractors.ida.function
-import capa.features.extractors.ida.basicblock
-from capa.features.extractors import FeatureExtractor
-
-
-def get_ea(self):
-    """ """
-    if isinstance(self, (idaapi.BasicBlock, idaapi.func_t)):
-        return self.start_ea
-    if isinstance(self, idaapi.insn_t):
-        return self.ea
-    raise TypeError
-
-
-def add_ea_int_cast(o):
-    """
-    dynamically add a cast-to-int (`__int__`) method to the given object
-    that returns the value of the `.ea` property.
-    this bit of skullduggery lets use cast viv-utils objects as ints.
-    the correct way of doing this is to update viv-utils (or subclass the objects here).
-    """
-    if sys.version_info[0] >= 3:
-        setattr(o, "__int__", types.MethodType(get_ea, o))
-    else:
-        setattr(o, "__int__", types.MethodType(get_ea, o, type(o)))
-    return o
-
-
-class IdaFeatureExtractor(FeatureExtractor):
-    def __init__(self):
-        super(IdaFeatureExtractor, self).__init__()
-
-    def get_base_address(self):
-        return idaapi.get_imagebase()
-
-    def extract_file_features(self):
-        for (feature, ea) in capa.features.extractors.ida.file.extract_features():
-            yield feature, ea
-
-    def get_functions(self):
-        import capa.features.extractors.ida.helpers as ida_helpers
-
-        # ignore library functions and thunk functions as identified by IDA
-        for f in ida_helpers.get_functions(skip_thunks=True, skip_libs=True):
-            yield add_ea_int_cast(f)
-
-    def extract_function_features(self, f):
-        for (feature, ea) in capa.features.extractors.ida.function.extract_features(f):
-            yield feature, ea
-
-    def get_basic_blocks(self, f):
-        for bb in idaapi.FlowChart(f, flags=idaapi.FC_PREDS):
-            yield add_ea_int_cast(bb)
-
-    def extract_basic_block_features(self, f, bb):
-        for (feature, ea) in capa.features.extractors.ida.basicblock.extract_features(f, bb):
-            yield feature, ea
-
-    def get_instructions(self, f, bb):
-        import capa.features.extractors.ida.helpers as ida_helpers
-
-        for insn in ida_helpers.get_instructions_in_range(bb.start_ea, bb.end_ea):
-            yield add_ea_int_cast(insn)
-
-    def extract_insn_features(self, f, bb, insn):
-        for (feature, ea) in capa.features.extractors.ida.insn.extract_features(f, bb, insn):
-            yield feature, ea

capa/features/extractors/ida/basicblock.py

@@ -1,24 +1,28 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-import sys
 import string
 import struct
+from typing import Tuple, Iterator
 
 import idaapi
 
 import capa.features.extractors.ida.helpers
-from capa.features import Characteristic
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address
 from capa.features.basicblock import BasicBlock
 from capa.features.extractors.ida import helpers
 from capa.features.extractors.helpers import MIN_STACKSTRING_LEN
+from capa.features.extractors.base_extractor import BBHandle, FunctionHandle
 
 
-def get_printable_len(op):
-    """ Return string length if all operand bytes are ascii or utf16-le printable
-
-        args:
-            op (IDA op_t)
-    """
+def get_printable_len(op: idaapi.op_t) -> int:
+    """Return string length if all operand bytes are ascii or utf16-le printable"""
     op_val = capa.features.extractors.ida.helpers.mask_op_val(op)
 
     if op.dtype == idaapi.dt_byte:
@@ -30,21 +34,14 @@ def get_printable_len(op):
     elif op.dtype == idaapi.dt_qword:
         chars = struct.pack("<Q", op_val)
     else:
-        raise ValueError("Unhandled operand data type 0x%x." % op.dtype)
+        raise ValueError(f"Unhandled operand data type 0x{op.dtype:x}.")
 
-    def is_printable_ascii(chars):
-        if sys.version_info[0] >= 3:
-            return all(c < 127 and chr(c) in string.printable for c in chars)
-        else:
-            return all(ord(c) < 127 and c in string.printable for c in chars)
+    def is_printable_ascii(chars_: bytes):
+        return all(c < 127 and chr(c) in string.printable for c in chars_)
 
-    def is_printable_utf16le(chars):
-        if sys.version_info[0] >= 3:
-            if all(c == 0x00 for c in chars[1::2]):
-                return is_printable_ascii(chars[::2])
-        else:
-            if all(c == "\x00" for c in chars[1::2]):
-                return is_printable_ascii(chars[::2])
+    def is_printable_utf16le(chars_: bytes):
+        if all(c == 0x00 for c in chars_[1::2]):
+            return is_printable_ascii(chars_[::2])
 
     if is_printable_ascii(chars):
         return idaapi.get_dtype_size(op.dtype)
@@ -55,12 +52,8 @@ def get_printable_len(op):
     return 0
 
 
-def is_mov_imm_to_stack(insn):
-    """ verify instruction moves immediate onto stack
-
-        args:
-            insn (IDA insn_t)
-    """
+def is_mov_imm_to_stack(insn: idaapi.insn_t) -> bool:
+    """verify instruction moves immediate onto stack"""
     if insn.Op2.type != idaapi.o_imm:
         return False
 
@@ -73,14 +66,10 @@ def is_mov_imm_to_stack(insn):
     return True
 
 
-def bb_contains_stackstring(f, bb):
-    """ check basic block for stackstring indicators
+def bb_contains_stackstring(f: idaapi.func_t, bb: idaapi.BasicBlock) -> bool:
+    """check basic block for stackstring indicators
 
-        true if basic block contains enough moves of constant bytes to the stack
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
+    true if basic block contains enough moves of constant bytes to the stack
     """
     count = 0
     for insn in capa.features.extractors.ida.helpers.get_instructions_in_range(bb.start_ea, bb.end_ea):
@@ -91,57 +80,27 @@ def bb_contains_stackstring(f, bb):
     return False
 
 
-def extract_bb_stackstring(f, bb):
-    """ extract stackstring indicators from basic block
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-    """
-    if bb_contains_stackstring(f, bb):
-        yield Characteristic("stack string"), bb.start_ea
+def extract_bb_stackstring(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract stackstring indicators from basic block"""
+    if bb_contains_stackstring(fh.inner, bbh.inner):
+        yield Characteristic("stack string"), bbh.address
 
 
-def extract_bb_tight_loop(f, bb):
-    """ extract tight loop indicators from a basic block
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-    """
-    if capa.features.extractors.ida.helpers.is_basic_block_tight_loop(bb):
-        yield Characteristic("tight loop"), bb.start_ea
+def extract_bb_tight_loop(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract tight loop indicators from a basic block"""
+    if capa.features.extractors.ida.helpers.is_basic_block_tight_loop(bbh.inner):
+        yield Characteristic("tight loop"), bbh.address
 
 
-def extract_features(f, bb):
-    """ extract basic block features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-    """
+def extract_features(fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract basic block features"""
     for bb_handler in BASIC_BLOCK_HANDLERS:
-        for (feature, ea) in bb_handler(f, bb):
-            yield feature, ea
-    yield BasicBlock(), bb.start_ea
+        for feature, addr in bb_handler(fh, bbh):
+            yield feature, addr
+    yield BasicBlock(), bbh.address
 
 
 BASIC_BLOCK_HANDLERS = (
     extract_bb_tight_loop,
     extract_bb_stackstring,
 )
-
-
-def main():
-    features = []
-    for f in helpers.get_functions(skip_thunks=True, skip_libs=True):
-        for bb in idaapi.FlowChart(f, flags=idaapi.FC_PREDS):
-            features.extend(list(extract_features(f, bb)))
-
-    import pprint
-
-    pprint.pprint(features)
-
-
-if __name__ == "__main__":
-    main()

capa/features/extractors/ida/extractor.py

@@ -0,0 +1,71 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import List, Tuple, Iterator
+
+import idaapi
+
+import capa.ida.helpers
+import capa.features.extractors.elf
+import capa.features.extractors.ida.file
+import capa.features.extractors.ida.insn
+import capa.features.extractors.ida.global_
+import capa.features.extractors.ida.function
+import capa.features.extractors.ida.basicblock
+from capa.features.common import Feature
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle, FeatureExtractor
+
+
+class IdaFeatureExtractor(FeatureExtractor):
+    def __init__(self):
+        super().__init__()
+        self.global_features: List[Tuple[Feature, Address]] = []
+        self.global_features.extend(capa.features.extractors.ida.file.extract_file_format())
+        self.global_features.extend(capa.features.extractors.ida.global_.extract_os())
+        self.global_features.extend(capa.features.extractors.ida.global_.extract_arch())
+
+    def get_base_address(self):
+        return AbsoluteVirtualAddress(idaapi.get_imagebase())
+
+    def extract_global_features(self):
+        yield from self.global_features
+
+    def extract_file_features(self):
+        yield from capa.features.extractors.ida.file.extract_features()
+
+    def get_functions(self) -> Iterator[FunctionHandle]:
+        import capa.features.extractors.ida.helpers as ida_helpers
+
+        # ignore library functions and thunk functions as identified by IDA
+        yield from ida_helpers.get_functions(skip_thunks=True, skip_libs=True)
+
+    @staticmethod
+    def get_function(ea: int) -> FunctionHandle:
+        f = idaapi.get_func(ea)
+        return FunctionHandle(address=AbsoluteVirtualAddress(f.start_ea), inner=f)
+
+    def extract_function_features(self, fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.ida.function.extract_features(fh)
+
+    def get_basic_blocks(self, fh: FunctionHandle) -> Iterator[BBHandle]:
+        import capa.features.extractors.ida.helpers as ida_helpers
+
+        for bb in ida_helpers.get_function_blocks(fh.inner):
+            yield BBHandle(address=AbsoluteVirtualAddress(bb.start_ea), inner=bb)
+
+    def extract_basic_block_features(self, fh: FunctionHandle, bbh: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.ida.basicblock.extract_features(fh, bbh)
+
+    def get_instructions(self, fh: FunctionHandle, bbh: BBHandle) -> Iterator[InsnHandle]:
+        import capa.features.extractors.ida.helpers as ida_helpers
+
+        for insn in ida_helpers.get_instructions_in_range(bbh.inner.start_ea, bbh.inner.end_ea):
+            yield InsnHandle(address=AbsoluteVirtualAddress(insn.ea), inner=insn)
+
+    def extract_insn_features(self, fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle):
+        yield from capa.features.extractors.ida.insn.extract_features(fh, bbh, ih)

capa/features/extractors/ida/file.py

@@ -1,26 +1,35 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
 import struct
+from typing import Tuple, Iterator
 
 import idc
 import idaapi
 import idautils
+import ida_entry
 
+import capa.features.extractors.common
 import capa.features.extractors.helpers
 import capa.features.extractors.strings
 import capa.features.extractors.ida.helpers
-from capa.features import String, Characteristic
-from capa.features.file import Export, Import, Section
+from capa.features.file import Export, Import, Section, FunctionName
+from capa.features.common import FORMAT_PE, FORMAT_ELF, Format, String, Feature, Characteristic
+from capa.features.address import NO_ADDRESS, Address, FileOffsetAddress, AbsoluteVirtualAddress
+
+MAX_OFFSET_PE_AFTER_MZ = 0x200
 
 
-def check_segment_for_pe(seg):
-    """ check segment for embedded PE
+def check_segment_for_pe(seg: idaapi.segment_t) -> Iterator[Tuple[int, int]]:
+    """check segment for embedded PE
 
-        adapted for IDA from:
-        https://github.com/vivisect/vivisect/blob/7be4037b1cecc4551b397f840405a1fc606f9b53/PE/carve.py#L19
-
-        args:
-            seg (IDA segment_t)
+    adapted for IDA from:
+    https://github.com/vivisect/vivisect/blob/91e8419a861f49779f18316f155311967e696836/PE/carve.py#L25
     """
     seg_max = seg.end_ea
     mz_xor = [
@@ -31,16 +40,17 @@ def check_segment_for_pe(seg):
         )
         for i in range(256)
     ]
-    todo = [
-        (capa.features.extractors.ida.helpers.find_byte_sequence(seg.start_ea, seg.end_ea, mzx), mzx, pex, i)
-        for mzx, pex, i in mz_xor
-    ]
-    todo = [(off, mzx, pex, i) for (off, mzx, pex, i) in todo if off != idaapi.BADADDR]
+
+    todo = []
+    for mzx, pex, i in mz_xor:
+        # find all segment offsets containing XOR'd "MZ" bytes
+        for off in capa.features.extractors.ida.helpers.find_byte_sequence(seg.start_ea, seg.end_ea, mzx):
+            todo.append((off, mzx, pex, i))
 
     while len(todo):
         off, mzx, pex, i = todo.pop()
 
-        # The MZ header has one field we will check e_lfanew is at 0x3c
+        # MZ header has one field we will check e_lfanew is at 0x3c
         e_lfanew = off + 0x3C
 
         if seg_max < (e_lfanew + 4):
@@ -48,88 +58,143 @@ def check_segment_for_pe(seg):
 
         newoff = struct.unpack("<I", capa.features.extractors.helpers.xor_static(idc.get_bytes(e_lfanew, 4), i))[0]
 
+        # assume XOR'd "PE" bytes exist within threshold
+        if newoff > MAX_OFFSET_PE_AFTER_MZ:
+            continue
+
         peoff = off + newoff
         if seg_max < (peoff + 2):
             continue
 
         if idc.get_bytes(peoff, 2) == pex:
-            yield (off, i)
-
-        nextres = capa.features.extractors.ida.helpers.find_byte_sequence(off + 1, seg.end_ea, mzx)
-        if nextres != -1:
-            todo.append((nextres, mzx, pex, i))
+            yield off, i
 
 
-def extract_file_embedded_pe():
-    """ extract embedded PE features
+def extract_file_embedded_pe() -> Iterator[Tuple[Feature, Address]]:
+    """extract embedded PE features
 
-        IDA must load resource sections for this to be complete
-            - '-R' from console
-            - Check 'Load resource sections' when opening binary in IDA manually
+    IDA must load resource sections for this to be complete
+        - '-R' from console
+        - Check 'Load resource sections' when opening binary in IDA manually
     """
     for seg in capa.features.extractors.ida.helpers.get_segments(skip_header_segments=True):
-        for (ea, _) in check_segment_for_pe(seg):
-            yield Characteristic("embedded pe"), ea
+        for ea, _ in check_segment_for_pe(seg):
+            yield Characteristic("embedded pe"), FileOffsetAddress(ea)
 
 
-def extract_file_export_names():
-    """ extract function exports """
-    for (_, _, ea, name) in idautils.Entries():
-        yield Export(name), ea
+def extract_file_export_names() -> Iterator[Tuple[Feature, Address]]:
+    """extract function exports"""
+    for _, ordinal, ea, name in idautils.Entries():
+        forwarded_name = ida_entry.get_entry_forwarder(ordinal)
+        if forwarded_name is None:
+            yield Export(name), AbsoluteVirtualAddress(ea)
+        else:
+            forwarded_name = capa.features.extractors.helpers.reformat_forwarded_export_name(forwarded_name)
+            yield Export(forwarded_name), AbsoluteVirtualAddress(ea)
+            yield Characteristic("forwarded export"), AbsoluteVirtualAddress(ea)
 
 
-def extract_file_import_names():
-    """ extract function imports
+def extract_file_import_names() -> Iterator[Tuple[Feature, Address]]:
+    """extract function imports
 
-        1. imports by ordinal:
-         - modulename.#ordinal
+    1. imports by ordinal:
+     - modulename.#ordinal
 
-        2. imports by name, results in two features to support importname-only
-           matching:
-         - modulename.importname
-         - importname
+    2. imports by name, results in two features to support importname-only
+       matching:
+     - modulename.importname
+     - importname
     """
-    for (ea, info) in capa.features.extractors.ida.helpers.get_file_imports().items():
-        if info[1]:
-            yield Import("%s.%s" % (info[0], info[1])), ea
-            yield Import(info[1]), ea
-        if info[2]:
-            yield Import("%s.#%s" % (info[0], str(info[2]))), ea
+    for ea, info in capa.features.extractors.ida.helpers.get_file_imports().items():
+        addr = AbsoluteVirtualAddress(ea)
+        if info[1] and info[2]:
+            # e.g. in mimikatz: ('cabinet', 'FCIAddFile', 11L)
+            # extract by name here and by ordinal below
+            for name in capa.features.extractors.helpers.generate_symbols(info[0], info[1]):
+                yield Import(name), addr
+            dll = info[0]
+            symbol = f"#{info[2]}"
+        elif info[1]:
+            dll = info[0]
+            symbol = info[1]
+        elif info[2]:
+            dll = info[0]
+            symbol = f"#{info[2]}"
+        else:
+            continue
+
+        for name in capa.features.extractors.helpers.generate_symbols(dll, symbol):
+            yield Import(name), addr
+
+    for ea, info in capa.features.extractors.ida.helpers.get_file_externs().items():
+        yield Import(info[1]), AbsoluteVirtualAddress(ea)
 
 
-def extract_file_section_names():
-    """ extract section names
+def extract_file_section_names() -> Iterator[Tuple[Feature, Address]]:
+    """extract section names
 
-        IDA must load resource sections for this to be complete
-            - '-R' from console
-            - Check 'Load resource sections' when opening binary in IDA manually
+    IDA must load resource sections for this to be complete
+        - '-R' from console
+        - Check 'Load resource sections' when opening binary in IDA manually
     """
     for seg in capa.features.extractors.ida.helpers.get_segments(skip_header_segments=True):
-        yield Section(idaapi.get_segm_name(seg)), seg.start_ea
+        yield Section(idaapi.get_segm_name(seg)), AbsoluteVirtualAddress(seg.start_ea)
 
 
-def extract_file_strings():
-    """ extract ASCII and UTF-16 LE strings
+def extract_file_strings() -> Iterator[Tuple[Feature, Address]]:
+    """extract ASCII and UTF-16 LE strings
 
-        IDA must load resource sections for this to be complete
-            - '-R' from console
-            - Check 'Load resource sections' when opening binary in IDA manually
+    IDA must load resource sections for this to be complete
+        - '-R' from console
+        - Check 'Load resource sections' when opening binary in IDA manually
     """
     for seg in capa.features.extractors.ida.helpers.get_segments():
         seg_buff = capa.features.extractors.ida.helpers.get_segment_buffer(seg)
 
+        # differing to common string extractor factor in segment offset here
         for s in capa.features.extractors.strings.extract_ascii_strings(seg_buff):
-            yield String(s.s), (seg.start_ea + s.offset)
+            yield String(s.s), FileOffsetAddress(seg.start_ea + s.offset)
 
         for s in capa.features.extractors.strings.extract_unicode_strings(seg_buff):
-            yield String(s.s), (seg.start_ea + s.offset)
+            yield String(s.s), FileOffsetAddress(seg.start_ea + s.offset)
 
 
-def extract_features():
-    """ extract file features """
+def extract_file_function_names() -> Iterator[Tuple[Feature, Address]]:
+    """
+    extract the names of statically-linked library functions.
+    """
+    for ea in idautils.Functions():
+        addr = AbsoluteVirtualAddress(ea)
+        if idaapi.get_func(ea).flags & idaapi.FUNC_LIB:
+            name = idaapi.get_name(ea)
+            yield FunctionName(name), addr
+            if name.startswith("_"):
+                # some linkers may prefix linked routines with a `_` to avoid name collisions.
+                # extract features for both the mangled and un-mangled representations.
+                # e.g. `_fwrite` -> `fwrite`
+                # see: https://stackoverflow.com/a/2628384/87207
+                yield FunctionName(name[1:]), addr
+
+
+def extract_file_format() -> Iterator[Tuple[Feature, Address]]:
+    file_info = idaapi.get_inf_structure()
+
+    if file_info.filetype in (idaapi.f_PE, idaapi.f_COFF):
+        yield Format(FORMAT_PE), NO_ADDRESS
+    elif file_info.filetype == idaapi.f_ELF:
+        yield Format(FORMAT_ELF), NO_ADDRESS
+    elif file_info.filetype == idaapi.f_BIN:
+        # no file type to return when processing a binary file, but we want to continue processing
+        return
+    else:
+        raise NotImplementedError(f"unexpected file format: {file_info.filetype}")
+
+
+def extract_features() -> Iterator[Tuple[Feature, Address]]:
+    """extract file features"""
     for file_handler in FILE_HANDLERS:
-        for feature, va in file_handler():
-            yield feature, va
+        for feature, addr in file_handler():
+            yield feature, addr
 
 
 FILE_HANDLERS = (
@@ -138,15 +203,6 @@ FILE_HANDLERS = (
     extract_file_strings,
     extract_file_section_names,
     extract_file_embedded_pe,
+    extract_file_function_names,
+    extract_file_format,
 )
-
-
-def main():
-    """ """
-    import pprint
-
-    pprint.pprint(list(extract_features()))
-
-
-if __name__ == "__main__":
-    main()

capa/features/extractors/ida/function.py

@@ -1,39 +1,31 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Tuple, Iterator
 
 import idaapi
 import idautils
 
 import capa.features.extractors.ida.helpers
-from capa.features import Characteristic
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
 from capa.features.extractors import loops
+from capa.features.extractors.base_extractor import FunctionHandle
 
 
-def extract_function_switch(f):
-    """ extract switch indicators from a function
-
-        arg:
-            f (IDA func_t)
-    """
-    if capa.features.extractors.ida.helpers.is_function_switch_statement(f):
-        yield Characteristic("switch"), f.start_ea
+def extract_function_calls_to(fh: FunctionHandle):
+    """extract callers to a function"""
+    for ea in idautils.CodeRefsTo(fh.inner.start_ea, True):
+        yield Characteristic("calls to"), AbsoluteVirtualAddress(ea)
 
 
-def extract_function_calls_to(f):
-    """ extract callers to a function
-
-        args:
-            f (IDA func_t)
-    """
-    for ea in idautils.CodeRefsTo(f.start_ea, True):
-        yield Characteristic("calls to"), ea
-
-
-def extract_function_loop(f):
-    """ extract loop indicators from a function
-
-        args:
-            f (IDA func_t)
-    """
+def extract_function_loop(fh: FunctionHandle):
+    """extract loop indicators from a function"""
+    f: idaapi.func_t = fh.inner
     edges = []
 
     # construct control flow graph
@@ -42,43 +34,19 @@ def extract_function_loop(f):
             edges.append((bb.start_ea, succ.start_ea))
 
     if loops.has_loop(edges):
-        yield Characteristic("loop"), f.start_ea
+        yield Characteristic("loop"), fh.address
 
 
-def extract_recursive_call(f):
-    """ extract recursive function call
-
-        args:
-            f (IDA func_t)
-    """
-    if capa.features.extractors.ida.helpers.is_function_recursive(f):
-        yield Characteristic("recursive call"), f.start_ea
+def extract_recursive_call(fh: FunctionHandle):
+    """extract recursive function call"""
+    if capa.features.extractors.ida.helpers.is_function_recursive(fh.inner):
+        yield Characteristic("recursive call"), fh.address
 
 
-def extract_features(f):
-    """ extract function features
-
-        arg:
-            f (IDA func_t)
-    """
+def extract_features(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
     for func_handler in FUNCTION_HANDLERS:
-        for (feature, ea) in func_handler(f):
-            yield feature, ea
+        for feature, addr in func_handler(fh):
+            yield feature, addr
 
 
-FUNCTION_HANDLERS = (extract_function_calls_to, extract_function_switch, extract_function_loop, extract_recursive_call)
-
-
-def main():
-    """ """
-    features = []
-    for f in capa.features.extractors.ida.get_functions(skip_thunks=True, skip_libs=True):
-        features.extend(list(extract_features(f)))
-
-    import pprint
-
-    pprint.pprint(features)
-
-
-if __name__ == "__main__":
-    main()
+FUNCTION_HANDLERS = (extract_function_calls_to, extract_function_loop, extract_recursive_call)

capa/features/extractors/ida/global_.py

@@ -0,0 +1,65 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+import contextlib
+from typing import Tuple, Iterator
+
+import idaapi
+import ida_loader
+
+import capa.ida.helpers
+import capa.features.extractors.elf
+from capa.features.common import OS, ARCH_I386, ARCH_AMD64, OS_WINDOWS, Arch, Feature
+from capa.features.address import NO_ADDRESS, Address
+
+logger = logging.getLogger(__name__)
+
+
+def extract_os() -> Iterator[Tuple[Feature, Address]]:
+    format_name: str = ida_loader.get_file_type_name()
+
+    if "PE" in format_name:
+        yield OS(OS_WINDOWS), NO_ADDRESS
+
+    elif "ELF" in format_name:
+        with contextlib.closing(capa.ida.helpers.IDAIO()) as f:
+            os = capa.features.extractors.elf.detect_elf_os(f)
+
+        yield OS(os), NO_ADDRESS
+
+    else:
+        # we likely end up here:
+        #  1. handling shellcode, or
+        #  2. handling a new file format (e.g. macho)
+        #
+        # for (1) we can't do much - its shellcode and all bets are off.
+        # we could maybe accept a further CLI argument to specify the OS,
+        # but i think this would be rarely used.
+        # rules that rely on OS conditions will fail to match on shellcode.
+        #
+        # for (2), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported file format: %s, will not guess OS", format_name)
+        return
+
+
+def extract_arch() -> Iterator[Tuple[Feature, Address]]:
+    info: idaapi.idainfo = idaapi.get_inf_structure()
+    if info.procname == "metapc" and info.is_64bit():
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+    elif info.procname == "metapc" and info.is_32bit():
+        yield Arch(ARCH_I386), NO_ADDRESS
+    elif info.procname == "metapc":
+        logger.debug("unsupported architecture: non-32-bit nor non-64-bit intel")
+        return
+    else:
+        # we likely end up here:
+        #  1. handling a new architecture (e.g. aarch64)
+        #
+        # for (1), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported architecture: %s", info.procname)
+        return

capa/features/extractors/ida/helpers.py

@@ -1,48 +1,62 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import sys
-import string
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import functools
+from typing import Any, Dict, Tuple, Iterator, Optional
 
 import idc
 import idaapi
 import idautils
+import ida_bytes
+import ida_segment
+
+from capa.features.address import AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import FunctionHandle
 
 
-def find_byte_sequence(start, end, seq):
-    """ find byte sequence
+def find_byte_sequence(start: int, end: int, seq: bytes) -> Iterator[int]:
+    """yield all ea of a given byte sequence
 
-        args:
-            start: min virtual address
-            end: max virtual address
-            seq: bytes to search e.g. b'\x01\x03'
+    args:
+        start: min virtual address
+        end: max virtual address
+        seq: bytes to search e.g. b"\x01\x03"
     """
-    if sys.version_info[0] >= 3:
-        return idaapi.find_binary(start, end, " ".join(["%02x" % b for b in seq]), 0, idaapi.SEARCH_DOWN)
-    else:
-        return idaapi.find_binary(start, end, " ".join(["%02x" % ord(b) for b in seq]), 0, idaapi.SEARCH_DOWN)
+    seqstr = " ".join([f"{b:02x}" for b in seq])
+    while True:
+        # TODO(mike-hunhoff): find_binary is deprecated. Please use ida_bytes.bin_search() instead.
+        # https://github.com/mandiant/capa/issues/1606
+        ea = idaapi.find_binary(start, end, seqstr, 0, idaapi.SEARCH_DOWN)
+        if ea == idaapi.BADADDR:
+            break
+        start = ea + 1
+        yield ea
 
 
-def get_functions(start=None, end=None, skip_thunks=False, skip_libs=False):
-    """ get functions, range optional
+def get_functions(
+    start: Optional[int] = None, end: Optional[int] = None, skip_thunks: bool = False, skip_libs: bool = False
+) -> Iterator[FunctionHandle]:
+    """get functions, range optional
 
-        args:
-            start: min virtual address
-            end: max virtual address
-
-        ret:
-            yield func_t*
+    args:
+        start: min virtual address
+        end: max virtual address
     """
     for ea in idautils.Functions(start=start, end=end):
         f = idaapi.get_func(ea)
         if not (skip_thunks and (f.flags & idaapi.FUNC_THUNK) or skip_libs and (f.flags & idaapi.FUNC_LIB)):
-            yield f
+            yield FunctionHandle(address=AbsoluteVirtualAddress(ea), inner=f)
 
 
-def get_segments(skip_header_segments=False):
-    """ get list of segments (sections) in the binary image
+def get_segments(skip_header_segments=False) -> Iterator[idaapi.segment_t]:
+    """get list of segments (sections) in the binary image
 
-        args:
-            skip_header_segments: IDA may load header segments - skip if set
+    args:
+        skip_header_segments: IDA may load header segments - skip if set
     """
     for n in range(idaapi.get_segm_qty()):
         seg = idaapi.getnseg(n)
@@ -50,10 +64,10 @@ def get_segments(skip_header_segments=False):
             yield seg
 
 
-def get_segment_buffer(seg):
-    """ return bytes stored in a given segment
+def get_segment_buffer(seg: idaapi.segment_t) -> bytes:
+    """return bytes stored in a given segment
 
-        decrease buffer size until IDA is able to read bytes from the segment
+    decrease buffer size until IDA is able to read bytes from the segment
     """
     buff = b""
     sz = seg.end_ea - seg.start_ea
@@ -68,9 +82,22 @@ def get_segment_buffer(seg):
     return buff if buff else b""
 
 
-def get_file_imports():
-    """ get file imports """
-    imports = {}
+def inspect_import(imports, library, ea, function, ordinal):
+    if function and function.startswith("__imp_"):
+        # handle mangled PE imports
+        function = function[len("__imp_") :]
+
+    if function and "@@" in function:
+        # handle mangled ELF imports, like "fopen@@glibc_2.2.5"
+        function, _, _ = function.partition("@@")
+
+    imports[ea] = (library.lower(), function, ordinal)
+    return True
+
+
+def get_file_imports() -> Dict[int, Tuple[str, str, int]]:
+    """get file imports"""
+    imports: Dict[int, Tuple[str, str, int]] = {}
 
     for idx in range(idaapi.get_import_module_qty()):
         library = idaapi.get_import_module_name(idx)
@@ -78,26 +105,38 @@ def get_file_imports():
         if not library:
             continue
 
-        def inspect_import(ea, function, ordinal):
-            if function and function.startswith("__imp_"):
-                # handle mangled names starting
-                function = function[len("__imp_") :]
-            imports[ea] = (library.lower(), function, ordinal)
-            return True
+        # IDA uses section names for the library of ELF imports, like ".dynsym".
+        # These are not useful to us, we may need to expand this list over time
+        # TODO(williballenthin): find all section names used by IDA
+        # https://github.com/mandiant/capa/issues/1419
+        if library == ".dynsym":
+            library = ""
 
-        idaapi.enum_import_names(idx, inspect_import)
+        cb = functools.partial(inspect_import, imports, library)
+        idaapi.enum_import_names(idx, cb)
 
     return imports
 
 
-def get_instructions_in_range(start, end):
-    """ yield instructions in range
+def get_file_externs() -> Dict[int, Tuple[str, str, int]]:
+    externs = {}
 
-        args:
-            start: virtual address (inclusive)
-            end: virtual address (exclusive)
-        yield:
-            (insn_t*)
+    for seg in get_segments(skip_header_segments=True):
+        if seg.type != ida_segment.SEG_XTRN:
+            continue
+
+        for ea in idautils.Functions(seg.start_ea, seg.end_ea):
+            externs[ea] = ("", idaapi.get_func_name(ea), -1)
+
+    return externs
+
+
+def get_instructions_in_range(start: int, end: int) -> Iterator[idaapi.insn_t]:
+    """yield instructions in range
+
+    args:
+        start: virtual address (inclusive)
+        end: virtual address (exclusive)
     """
     for head in idautils.Heads(start, end):
         insn = idautils.DecodeInstruction(head)
@@ -105,8 +144,8 @@ def get_instructions_in_range(start, end):
             yield insn
 
 
-def is_operand_equal(op1, op2):
-    """ compare two IDA op_t """
+def is_operand_equal(op1: idaapi.op_t, op2: idaapi.op_t) -> bool:
+    """compare two IDA op_t"""
     if op1.flags != op2.flags:
         return False
 
@@ -131,8 +170,8 @@ def is_operand_equal(op1, op2):
     return True
 
 
-def is_basic_block_equal(bb1, bb2):
-    """ compare two IDA BasicBlock """
+def is_basic_block_equal(bb1: idaapi.BasicBlock, bb2: idaapi.BasicBlock) -> bool:
+    """compare two IDA BasicBlock"""
     if bb1.start_ea != bb2.start_ea:
         return False
 
@@ -145,13 +184,17 @@ def is_basic_block_equal(bb1, bb2):
     return True
 
 
-def basic_block_size(bb):
-    """ calculate size of basic block """
+def basic_block_size(bb: idaapi.BasicBlock) -> int:
+    """calculate size of basic block"""
     return bb.end_ea - bb.start_ea
 
 
-def read_bytes_at(ea, count):
+def read_bytes_at(ea: int, count: int) -> bytes:
     """ """
+    # check if byte has a value, see get_wide_byte doc
+    if not idc.is_loaded(ea):
+        return b""
+
     segm_end = idc.get_segm_end(ea)
     if ea + count > segm_end:
         return idc.get_bytes(ea, segm_end - ea)
@@ -159,10 +202,10 @@ def read_bytes_at(ea, count):
         return idc.get_bytes(ea, count)
 
 
-def find_string_at(ea, min=4):
-    """ check if ASCII string exists at a given virtual address """
+def find_string_at(ea: int, min_: int = 4) -> str:
+    """check if ASCII string exists at a given virtual address"""
     found = idaapi.get_strlit_contents(ea, -1, idaapi.STRTYPE_C)
-    if found and len(found) > min:
+    if found and len(found) >= min_:
         try:
             found = found.decode("ascii")
             # hacky check for IDA bug; get_strlit_contents also reads Unicode as
@@ -176,17 +219,18 @@ def find_string_at(ea, min=4):
     return ""
 
 
-def get_op_phrase_info(op):
-    """ parse phrase features from operand
+def get_op_phrase_info(op: idaapi.op_t) -> Dict:
+    """parse phrase features from operand
 
-        Pretty much dup of sark's implementation:
-            https://github.com/tmr232/Sark/blob/master/sark/code/instruction.py#L28-L73
+    Pretty much dup of sark's implementation:
+        https://github.com/tmr232/Sark/blob/master/sark/code/instruction.py#L28-L73
     """
     if op.type not in (idaapi.o_phrase, idaapi.o_displ):
         return {}
 
     scale = 1 << ((op.specflag2 & 0xC0) >> 6)
-    offset = op.addr
+    # IDA ea_t may be 32- or 64-bit; we assume displacement can only be 32-bit
+    offset = op.addr & 0xFFFFFFFF
 
     if op.specflag1 == 0:
         index = None
@@ -213,41 +257,45 @@ def get_op_phrase_info(op):
     return {"base": base, "index": index, "scale": scale, "offset": offset}
 
 
-def is_op_write(insn, op):
-    """ Check if an operand is written to (destination operand) """
+def is_op_write(insn: idaapi.insn_t, op: idaapi.op_t) -> bool:
+    """Check if an operand is written to (destination operand)"""
     return idaapi.has_cf_chg(insn.get_canon_feature(), op.n)
 
 
-def is_op_read(insn, op):
-    """ Check if an operand is read from (source operand) """
+def is_op_read(insn: idaapi.insn_t, op: idaapi.op_t) -> bool:
+    """Check if an operand is read from (source operand)"""
     return idaapi.has_cf_use(insn.get_canon_feature(), op.n)
 
 
-def is_sp_modified(insn):
-    """ determine if instruction modifies SP, ESP, RSP """
-    for op in get_insn_ops(insn, target_ops=(idaapi.o_reg,)):
-        if op.reg == idautils.procregs.sp.reg and is_op_write(insn, op):
-            # register is stack and written
-            return True
-    return False
+def is_op_offset(insn: idaapi.insn_t, op: idaapi.op_t) -> bool:
+    """Check is an operand has been marked as an offset (by auto-analysis or manually)"""
+    flags = idaapi.get_flags(insn.ea)
+    return ida_bytes.is_off(flags, op.n)
 
 
-def is_bp_modified(insn):
-    """ check if instruction modifies BP, EBP, RBP """
-    for op in get_insn_ops(insn, target_ops=(idaapi.o_reg,)):
-        if op.reg == idautils.procregs.bp.reg and is_op_write(insn, op):
-            # register is base and written
-            return True
-    return False
+def is_sp_modified(insn: idaapi.insn_t) -> bool:
+    """determine if instruction modifies SP, ESP, RSP"""
+    return any(
+        op.reg == idautils.procregs.sp.reg and is_op_write(insn, op)
+        for op in get_insn_ops(insn, target_ops=(idaapi.o_reg,))
+    )
 
 
-def is_frame_register(reg):
-    """ check if register is sp or bp """
+def is_bp_modified(insn: idaapi.insn_t) -> bool:
+    """check if instruction modifies BP, EBP, RBP"""
+    return any(
+        op.reg == idautils.procregs.bp.reg and is_op_write(insn, op)
+        for op in get_insn_ops(insn, target_ops=(idaapi.o_reg,))
+    )
+
+
+def is_frame_register(reg: int) -> bool:
+    """check if register is sp or bp"""
     return reg in (idautils.procregs.sp.reg, idautils.procregs.bp.reg)
 
 
-def get_insn_ops(insn, target_ops=()):
-    """ yield op_t for instruction, filter on type if specified """
+def get_insn_ops(insn: idaapi.insn_t, target_ops: Optional[Tuple[Any]] = None) -> idaapi.op_t:
+    """yield op_t for instruction, filter on type if specified"""
     for op in insn.ops:
         if op.type == idaapi.o_void:
             # avoid looping all 6 ops if only subset exists
@@ -257,21 +305,21 @@ def get_insn_ops(insn, target_ops=()):
         yield op
 
 
-def is_op_stack_var(ea, index):
-    """ check if operand is a stack variable """
+def is_op_stack_var(ea: int, index: int) -> bool:
+    """check if operand is a stack variable"""
     return idaapi.is_stkvar(idaapi.get_flags(ea), index)
 
 
-def mask_op_val(op):
-    """ mask value by data type
+def mask_op_val(op: idaapi.op_t) -> int:
+    """mask value by data type
 
-        necessary due to a bug in AMD64
+    necessary due to a bug in AMD64
 
-        Example:
-            .rsrc:0054C12C mov [ebp+var_4], 0FFFFFFFFh
+    Example:
+        .rsrc:0054C12C mov [ebp+var_4], 0FFFFFFFFh
 
-            insn.Op2.dtype == idaapi.dt_dword
-            insn.Op2.value == 0xffffffffffffffff
+        insn.Op2.dtype == idaapi.dt_dword
+        insn.Op2.value == 0xffffffffffffffff
     """
     masks = {
         idaapi.dt_byte: 0xFF,
@@ -282,42 +330,15 @@ def mask_op_val(op):
     return masks.get(op.dtype, op.value) & op.value
 
 
-def is_function_recursive(f):
-    """ check if function is recursive
-
-        args:
-            f (IDA func_t)
-    """
-    for ref in idautils.CodeRefsTo(f.start_ea, True):
-        if f.contains(ref):
-            return True
-    return False
+def is_function_recursive(f: idaapi.func_t) -> bool:
+    """check if function is recursive"""
+    return any(f.contains(ref) for ref in idautils.CodeRefsTo(f.start_ea, True))
 
 
-def is_function_switch_statement(f):
-    """ check a function for switch statement indicators
+def is_basic_block_tight_loop(bb: idaapi.BasicBlock) -> bool:
+    """check basic block loops to self
 
-        adapted from:
-        https://reverseengineering.stackexchange.com/questions/17548/calc-switch-cases-in-idapython-cant-iterate-over-results?rq=1
-
-        arg:
-            f (IDA func_t)
-    """
-    for (start, end) in idautils.Chunks(f.start_ea):
-        for head in idautils.Heads(start, end):
-            if idaapi.get_switch_info(head):
-                return True
-    return False
-
-
-def is_basic_block_tight_loop(bb):
-    """ check basic block loops to self
-
-        true if last instruction in basic block branches to basic block start
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
+    true if last instruction in basic block branches to basic block start
     """
     bb_end = idc.prev_head(bb.end_ea)
     if bb.start_ea < bb_end:
@@ -325,3 +346,49 @@ def is_basic_block_tight_loop(bb):
             if ref == bb.start_ea:
                 return True
     return False
+
+
+def find_data_reference_from_insn(insn: idaapi.insn_t, max_depth: int = 10) -> int:
+    """search for data reference from instruction, return address of instruction if no reference exists"""
+    depth = 0
+    ea = insn.ea
+
+    while True:
+        data_refs = list(idautils.DataRefsFrom(ea))
+
+        if len(data_refs) != 1:
+            # break if no refs or more than one ref (assume nested pointers only have one data reference)
+            break
+
+        if ea == data_refs[0]:
+            # break if circular reference
+            break
+
+        if not idaapi.is_mapped(data_refs[0]):
+            # break if address is not mapped
+            break
+
+        depth += 1
+        if depth > max_depth:
+            # break if max depth
+            break
+
+        ea = data_refs[0]
+
+    return ea
+
+
+def get_function_blocks(f: idaapi.func_t) -> Iterator[idaapi.BasicBlock]:
+    """yield basic blocks contained in specified function"""
+    # leverage idaapi.FC_NOEXT flag to ignore useless external blocks referenced by the function
+    yield from idaapi.FlowChart(f, flags=(idaapi.FC_PREDS | idaapi.FC_NOEXT))
+
+
+def is_basic_block_return(bb: idaapi.BasicBlock) -> bool:
+    """check if basic block is return block"""
+    return bb.type == idaapi.fcb_ret
+
+
+def has_sib(oper: idaapi.op_t) -> bool:
+    # via: https://reverseengineering.stackexchange.com/a/14300
+    return oper.specflag1 == 1

capa/features/extractors/ida/insn.py

@@ -1,4 +1,11 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Any, Dict, Tuple, Iterator
 
 import idc
 import idaapi
@@ -6,68 +13,112 @@ import idautils
 
 import capa.features.extractors.helpers
 import capa.features.extractors.ida.helpers
-from capa.features import MAX_BYTES_FEATURE_SIZE, Bytes, String, Characteristic
-from capa.features.insn import Number, Offset, Mnemonic
+from capa.features.insn import API, MAX_STRUCTURE_SIZE, Number, Offset, Mnemonic, OperandNumber, OperandOffset
+from capa.features.common import MAX_BYTES_FEATURE_SIZE, THUNK_CHAIN_DEPTH_DELTA, Bytes, String, Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle
 
-_file_imports_cache = None
+# security cookie checks may perform non-zeroing XORs, these are expected within a certain
+# byte range within the first and returning basic blocks, this helps to reduce FP features
+SECURITY_COOKIE_BYTES_DELTA = 0x40
 
 
-def get_imports():
-    """ """
-    global _file_imports_cache
-    if _file_imports_cache is None:
-        _file_imports_cache = capa.features.extractors.ida.helpers.get_file_imports()
-    return _file_imports_cache
+def get_imports(ctx: Dict[str, Any]) -> Dict[int, Any]:
+    if "imports_cache" not in ctx:
+        ctx["imports_cache"] = capa.features.extractors.ida.helpers.get_file_imports()
+    return ctx["imports_cache"]
 
 
-def check_for_api_call(insn):
-    """ check instruction for API call """
-    if not idaapi.is_call_insn(insn):
+def get_externs(ctx: Dict[str, Any]) -> Dict[int, Any]:
+    if "externs_cache" not in ctx:
+        ctx["externs_cache"] = capa.features.extractors.ida.helpers.get_file_externs()
+    return ctx["externs_cache"]
+
+
+def check_for_api_call(insn: idaapi.insn_t, funcs: Dict[int, Any]) -> Iterator[Any]:
+    """check instruction for API call"""
+    info = ()
+    ref = insn.ea
+
+    # attempt to resolve API calls by following chained thunks to a reasonable depth
+    for _ in range(THUNK_CHAIN_DEPTH_DELTA):
+        # assume only one code/data ref when resolving "call" or "jmp"
+        try:
+            ref = tuple(idautils.CodeRefsFrom(ref, False))[0]
+        except IndexError:
+            try:
+                # thunks may be marked as data refs
+                ref = tuple(idautils.DataRefsFrom(ref))[0]
+            except IndexError:
+                break
+
+        info = funcs.get(ref, ())
+        if info:
+            break
+
+        f = idaapi.get_func(ref)
+        if not f or not (f.flags & idaapi.FUNC_THUNK):
+            break
+
+    if info:
+        yield info
+
+
+def extract_insn_api_features(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse instruction API features
+
+    example:
+       call dword [0x00473038]
+    """
+    insn: idaapi.insn_t = ih.inner
+
+    if insn.get_canon_mnem() not in ("call", "jmp"):
         return
 
-    for ref in idautils.CodeRefsFrom(insn.ea, False):
-        info = get_imports().get(ref, ())
-        if info:
-            yield "%s.%s" % (info[0], info[1])
-        else:
-            f = idaapi.get_func(ref)
-            # check if call to thunk
-            # TODO: first instruction might not always be the thunk
-            if f and (f.flags & idaapi.FUNC_THUNK):
-                for thunk_ref in idautils.DataRefsFrom(ref):
-                    # TODO: always data ref for thunk??
-                    info = get_imports().get(thunk_ref, ())
-                    if info:
-                        yield "%s.%s" % (info[0], info[1])
+    # check calls to imported functions
+    for api in check_for_api_call(insn, get_imports(fh.ctx)):
+        # tuple (<module>, <function>, <ordinal>)
+        for name in capa.features.extractors.helpers.generate_symbols(api[0], api[1]):
+            yield API(name), ih.address
+
+    # check calls to extern functions
+    for api in check_for_api_call(insn, get_externs(fh.ctx)):
+        # tuple (<module>, <function>, <ordinal>)
+        yield API(api[1]), ih.address
+
+    # extract IDA/FLIRT recognized API functions
+    targets = tuple(idautils.CodeRefsFrom(insn.ea, False))
+    if not targets:
+        return
+
+    target = targets[0]
+    target_func = idaapi.get_func(target)
+    if not target_func or target_func.start_ea != target:
+        # not a function (start)
+        return
+
+    if target_func.flags & idaapi.FUNC_LIB:
+        name = idaapi.get_name(target_func.start_ea)
+        yield API(name), ih.address
+        if name.startswith("_"):
+            # some linkers may prefix linked routines with a `_` to avoid name collisions.
+            # extract features for both the mangled and un-mangled representations.
+            # e.g. `_fwrite` -> `fwrite`
+            # see: https://stackoverflow.com/a/2628384/87207
+            yield API(name[1:]), ih.address
 
 
-def extract_insn_api_features(f, bb, insn):
-    """ parse instruction API features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-
-        example:
-            call dword [0x00473038]
+def extract_insn_number_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
-    for api in check_for_api_call(insn):
-        for (feature, ea) in capa.features.extractors.helpers.generate_api_features(api, insn.ea):
-            yield feature, ea
-
-
-def extract_insn_number_features(f, bb, insn):
-    """ parse instruction number features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-
-        example:
-            push    3136B0h         ; dwControlCode
+    parse instruction number features
+    example:
+        push    3136B0h         ; dwControlCode
     """
+    insn: idaapi.insn_t = ih.inner
+
     if idaapi.is_ret_insn(insn):
         # skip things like:
         #   .text:0042250E retn 8
@@ -78,81 +129,137 @@ def extract_insn_number_features(f, bb, insn):
         #   .text:00401145 add esp, 0Ch
         return
 
-    for op in capa.features.extractors.ida.helpers.get_insn_ops(insn, target_ops=(idaapi.o_imm,)):
-        const = capa.features.extractors.ida.helpers.mask_op_val(op)
-        if not idaapi.is_mapped(const):
-            yield Number(const), insn.ea
+    for i, op in enumerate(insn.ops):
+        if op.type == idaapi.o_void:
+            break
+        if op.type not in (idaapi.o_imm, idaapi.o_mem):
+            continue
+        # skip things like:
+        #   .text:00401100 shr eax, offset loc_C
+        if capa.features.extractors.ida.helpers.is_op_offset(insn, op):
+            continue
+
+        if op.type == idaapi.o_imm:
+            const = capa.features.extractors.ida.helpers.mask_op_val(op)
+        else:
+            const = op.addr
+
+        yield Number(const), ih.address
+        yield OperandNumber(i, const), ih.address
+
+        if insn.itype == idaapi.NN_add and 0 < const < MAX_STRUCTURE_SIZE and op.type == idaapi.o_imm:
+            # for pattern like:
+            #
+            #     add eax, 0x10
+            #
+            # assume 0x10 is also an offset (imagine eax is a pointer).
+            yield Offset(const), ih.address
+            yield OperandOffset(i, const), ih.address
 
 
-def extract_insn_bytes_features(f, bb, insn):
-    """ parse referenced byte sequences
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-
-        example:
-            push    offset iid_004118d4_IShellLinkA ; riid
+def extract_insn_bytes_features(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """
+    parse referenced byte sequences
+    example:
+        push    offset iid_004118d4_IShellLinkA ; riid
+    """
+    insn: idaapi.insn_t = ih.inner
+
     if idaapi.is_call_insn(insn):
-        # ignore call instructions
         return
 
-    for ref in idautils.DataRefsFrom(insn.ea):
+    ref = capa.features.extractors.ida.helpers.find_data_reference_from_insn(insn)
+    if ref != insn.ea:
         extracted_bytes = capa.features.extractors.ida.helpers.read_bytes_at(ref, MAX_BYTES_FEATURE_SIZE)
         if extracted_bytes and not capa.features.extractors.helpers.all_zeros(extracted_bytes):
-            yield Bytes(extracted_bytes), insn.ea
+            if not capa.features.extractors.ida.helpers.find_string_at(ref):
+                # don't extract byte features for obvious strings
+                yield Bytes(extracted_bytes), ih.address
 
 
-def extract_insn_string_features(f, bb, insn):
-    """ parse instruction string features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-
-        example:
-            push offset aAcr     ; "ACR  > "
+def extract_insn_string_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
-    for ref in idautils.DataRefsFrom(insn.ea):
+    parse instruction string features
+
+    example:
+        push offset aAcr     ; "ACR  > "
+    """
+    insn: idaapi.insn_t = ih.inner
+
+    ref = capa.features.extractors.ida.helpers.find_data_reference_from_insn(insn)
+    if ref != insn.ea:
         found = capa.features.extractors.ida.helpers.find_string_at(ref)
         if found:
-            yield String(found), insn.ea
+            yield String(found), ih.address
 
 
-def extract_insn_offset_features(f, bb, insn):
-    """ parse instruction structure offset features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-
-        example:
-            .text:0040112F cmp [esi+4], ebx
+def extract_insn_offset_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
-    for op in capa.features.extractors.ida.helpers.get_insn_ops(insn, target_ops=(idaapi.o_phrase, idaapi.o_displ)):
+    parse instruction structure offset features
+
+    example:
+        .text:0040112F cmp [esi+4], ebx
+    """
+    insn: idaapi.insn_t = ih.inner
+
+    for i, op in enumerate(insn.ops):
+        if op.type == idaapi.o_void:
+            break
+        if op.type not in (idaapi.o_phrase, idaapi.o_displ):
+            continue
         if capa.features.extractors.ida.helpers.is_op_stack_var(insn.ea, op.n):
             continue
+
         p_info = capa.features.extractors.ida.helpers.get_op_phrase_info(op)
-        op_off = p_info.get("offset", 0)
-        if 0 == op_off:
+
+        op_off = p_info.get("offset")
+        if op_off is None:
             continue
+
         if idaapi.is_mapped(op_off):
             # Ignore:
             #   mov esi, dword_1005B148[esi]
             continue
-        yield Offset(op_off), insn.ea
+
+        # I believe that IDA encodes all offsets as two's complement in a u32.
+        # a 64-bit displacement isn't a thing, see:
+        # https://stackoverflow.com/questions/31853189/x86-64-assembly-why-displacement-not-64-bits
+        op_off = capa.features.extractors.helpers.twos_complement(op_off, 32)
+
+        yield Offset(op_off), ih.address
+        yield OperandOffset(i, op_off), ih.address
+
+        if (
+            insn.itype == idaapi.NN_lea
+            and i == 1
+            # o_displ is used for both:
+            #   [eax+1]
+            #   [eax+ebx+2]
+            and op.type == idaapi.o_displ
+            # but the SIB is only present for [eax+ebx+2]
+            # which we don't want
+            and not capa.features.extractors.ida.helpers.has_sib(op)
+        ):
+            # for pattern like:
+            #
+            #     lea eax, [ebx + 1]
+            #
+            # assume 1 is also an offset (imagine ebx is a zero register).
+            yield Number(op_off), ih.address
+            yield OperandNumber(i, op_off), ih.address
 
 
-def contains_stack_cookie_keywords(s):
-    """ check if string contains stack cookie keywords
+def contains_stack_cookie_keywords(s: str) -> bool:
+    """
+    check if string contains stack cookie keywords
 
-        Examples:
-            xor     ecx, ebp ; StackCookie
-            mov     eax, ___security_cookie
+    Examples:
+        xor     ecx, ebp ; StackCookie
+        mov     eax, ___security_cookie
     """
     if not s:
         return False
@@ -162,31 +269,31 @@ def contains_stack_cookie_keywords(s):
     return any(keyword in s for keyword in ("stack", "security"))
 
 
-def bb_stack_cookie_registers(bb):
-    """ scan basic block for stack cookie operations
+def bb_stack_cookie_registers(bb: idaapi.BasicBlock) -> Iterator[int]:
+    """scan basic block for stack cookie operations
 
-        yield registers ids that may have been used for stack cookie operations
+    yield registers ids that may have been used for stack cookie operations
 
-        assume instruction that sets stack cookie and nzxor exist in same block
-        and stack cookie register is not modified prior to nzxor
+    assume instruction that sets stack cookie and nzxor exist in same block
+    and stack cookie register is not modified prior to nzxor
 
-        Example:
-            .text:004062DA mov     eax, ___security_cookie <-- stack cookie
-            .text:004062DF mov     ecx, eax
-            .text:004062E1 mov     ebx, [esi]
-            .text:004062E3 and     ecx, 1Fh
-            .text:004062E6 mov     edi, [esi+4]
-            .text:004062E9 xor     ebx, eax
-            .text:004062EB mov     esi, [esi+8]
-            .text:004062EE xor     edi, eax <-- ignore
-            .text:004062F0 xor     esi, eax <-- ignore
-            .text:004062F2 ror     edi, cl
-            .text:004062F4 ror     esi, cl
-            .text:004062F6 ror     ebx, cl
-            .text:004062F8 cmp     edi, esi
-            .text:004062FA jnz     loc_40639D
+    Example:
+        .text:004062DA mov     eax, ___security_cookie <-- stack cookie
+        .text:004062DF mov     ecx, eax
+        .text:004062E1 mov     ebx, [esi]
+        .text:004062E3 and     ecx, 1Fh
+        .text:004062E6 mov     edi, [esi+4]
+        .text:004062E9 xor     ebx, eax
+        .text:004062EB mov     esi, [esi+8]
+        .text:004062EE xor     edi, eax <-- ignore
+        .text:004062F0 xor     esi, eax <-- ignore
+        .text:004062F2 ror     edi, cl
+        .text:004062F4 ror     esi, cl
+        .text:004062F6 ror     ebx, cl
+        .text:004062F8 cmp     edi, esi
+        .text:004062FA jnz     loc_40639D
 
-        TODO: this is expensive, but necessary?...
+    TODO: this is expensive, but necessary?...
     """
     for insn in capa.features.extractors.ida.helpers.get_instructions_in_range(bb.start_ea, bb.end_ea):
         if contains_stack_cookie_keywords(idc.GetDisasm(insn.ea)):
@@ -196,12 +303,37 @@ def bb_stack_cookie_registers(bb):
                     yield op.reg
 
 
-def is_nzxor_stack_cookie(f, bb, insn):
-    """ check if nzxor is related to stack cookie """
+def is_nzxor_stack_cookie_delta(f: idaapi.func_t, bb: idaapi.BasicBlock, insn: idaapi.insn_t) -> bool:
+    """check if nzxor exists within stack cookie delta"""
+    # security cookie check should use SP or BP
+    if not capa.features.extractors.ida.helpers.is_frame_register(insn.Op2.reg):
+        return False
+
+    f_bbs = tuple(capa.features.extractors.ida.helpers.get_function_blocks(f))
+
+    # expect security cookie init in first basic block within first bytes (instructions)
+    if capa.features.extractors.ida.helpers.is_basic_block_equal(bb, f_bbs[0]) and insn.ea < (
+        bb.start_ea + SECURITY_COOKIE_BYTES_DELTA
+    ):
+        return True
+
+    # ... or within last bytes (instructions) before a return
+    if capa.features.extractors.ida.helpers.is_basic_block_return(bb) and insn.ea > (
+        bb.start_ea + capa.features.extractors.ida.helpers.basic_block_size(bb) - SECURITY_COOKIE_BYTES_DELTA
+    ):
+        return True
+
+    return False
+
+
+def is_nzxor_stack_cookie(f: idaapi.func_t, bb: idaapi.BasicBlock, insn: idaapi.insn_t) -> bool:
+    """check if nzxor is related to stack cookie"""
     if contains_stack_cookie_keywords(idaapi.get_cmt(insn.ea, False)):
         # Example:
         #   xor     ecx, ebp        ; StackCookie
         return True
+    if is_nzxor_stack_cookie_delta(f, bb, insn):
+        return True
     stack_cookie_regs = tuple(bb_stack_cookie_registers(bb))
     if any(op_reg in stack_cookie_regs for op_reg in (insn.Op1.reg, insn.Op2.reg)):
         # Example:
@@ -211,89 +343,111 @@ def is_nzxor_stack_cookie(f, bb, insn):
     return False
 
 
-def extract_insn_nzxor_characteristic_features(f, bb, insn):
-    """ parse instruction non-zeroing XOR instruction
-
-        ignore expected non-zeroing XORs, e.g. security cookies
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
+def extract_insn_nzxor_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
-    if insn.itype != idaapi.NN_xor:
+    parse instruction non-zeroing XOR instruction
+    ignore expected non-zeroing XORs, e.g. security cookies
+    """
+    insn: idaapi.insn_t = ih.inner
+
+    if insn.itype not in (idaapi.NN_xor, idaapi.NN_xorpd, idaapi.NN_xorps, idaapi.NN_pxor):
         return
     if capa.features.extractors.ida.helpers.is_operand_equal(insn.Op1, insn.Op2):
         return
-    if is_nzxor_stack_cookie(f, bb, insn):
+    if is_nzxor_stack_cookie(fh.inner, bbh.inner, insn):
         return
-    yield Characteristic("nzxor"), insn.ea
+    yield Characteristic("nzxor"), ih.address
 
 
-def extract_insn_mnemonic_features(f, bb, insn):
-    """ parse instruction mnemonic features
+def extract_insn_mnemonic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction mnemonic features"""
+    yield Mnemonic(idc.print_insn_mnem(ih.inner.ea)), ih.address
 
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
+
+def extract_insn_obfs_call_plus_5_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
-    yield Mnemonic(insn.get_canon_mnem()), insn.ea
-
-
-def extract_insn_peb_access_characteristic_features(f, bb, insn):
-    """ parse instruction peb access
-
-        fs:[0x30] on x86, gs:[0x60] on x64
-
-        TODO:
-            IDA should be able to do this..
+    parse call $+5 instruction from the given instruction.
     """
+    insn: idaapi.insn_t = ih.inner
+
+    if not idaapi.is_call_insn(insn):
+        return
+
+    if insn.ea + 5 == idc.get_operand_value(insn.ea, 0):
+        yield Characteristic("call $+5"), ih.address
+
+
+def extract_insn_peb_access_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction peb access
+
+    fs:[0x30] on x86, gs:[0x60] on x64
+
+    TODO:
+        IDA should be able to do this..
+    """
+    insn: idaapi.insn_t = ih.inner
+
     if insn.itype not in (idaapi.NN_push, idaapi.NN_mov):
         return
 
-    if all(map(lambda op: op.type != idaapi.o_mem, insn.ops)):
+    if all(op.type != idaapi.o_mem for op in insn.ops):
         # try to optimize for only memory references
         return
 
     disasm = idc.GetDisasm(insn.ea)
 
     if " fs:30h" in disasm or " gs:60h" in disasm:
-        # TODO: replace above with proper IDA
-        yield Characteristic("peb access"), insn.ea
+        # TODO(mike-hunhoff): use proper IDA API for fetching segment access
+        # scanning the disassembly text is a hack.
+        # https://github.com/mandiant/capa/issues/1605
+        yield Characteristic("peb access"), ih.address
 
 
-def extract_insn_segment_access_features(f, bb, insn):
-    """ parse instruction fs or gs access
+def extract_insn_segment_access_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse instruction fs or gs access
 
-        TODO:
-            IDA should be able to do this...
+    TODO:
+        IDA should be able to do this...
     """
-    if all(map(lambda op: op.type != idaapi.o_mem, insn.ops)):
+    insn: idaapi.insn_t = ih.inner
+
+    if all(op.type != idaapi.o_mem for op in insn.ops):
         # try to optimize for only memory references
         return
 
     disasm = idc.GetDisasm(insn.ea)
 
     if " fs:" in disasm:
-        # TODO: replace above with proper IDA
-        yield Characteristic("fs access"), insn.ea
+        # TODO(mike-hunhoff): use proper IDA API for fetching segment access
+        # scanning the disassembly text is a hack.
+        # https://github.com/mandiant/capa/issues/1605
+        yield Characteristic("fs access"), ih.address
 
     if " gs:" in disasm:
-        # TODO: replace above with proper IDA
-        yield Characteristic("gs access"), insn.ea
+        # TODO(mike-hunhoff): use proper IDA API for fetching segment access
+        # scanning the disassembly text is a hack.
+        # https://github.com/mandiant/capa/issues/1605
+        yield Characteristic("gs access"), ih.address
 
 
-def extract_insn_cross_section_cflow(f, bb, insn):
-    """ inspect the instruction for a CALL or JMP that crosses section boundaries
+def extract_insn_cross_section_cflow(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """inspect the instruction for a CALL or JMP that crosses section boundaries"""
+    insn: idaapi.insn_t = ih.inner
 
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-    """
     for ref in idautils.CodeRefsFrom(insn.ea, False):
-        if ref in get_imports().keys():
+        if ref in get_imports(fh.ctx):
             # ignore API calls
             continue
         if not idaapi.getseg(ref):
@@ -301,50 +455,40 @@ def extract_insn_cross_section_cflow(f, bb, insn):
             continue
         if idaapi.getseg(ref) == idaapi.getseg(insn.ea):
             continue
-        yield Characteristic("cross section flow"), insn.ea
+        yield Characteristic("cross section flow"), ih.address
 
 
-def extract_function_calls_from(f, bb, insn):
-    """ extract functions calls from features
+def extract_function_calls_from(fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract functions calls from features
 
-        most relevant at the function scope, however, its most efficient to extract at the instruction scope
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
+    most relevant at the function scope, however, its most efficient to extract at the instruction scope
     """
+    insn: idaapi.insn_t = ih.inner
+
     if idaapi.is_call_insn(insn):
         for ref in idautils.CodeRefsFrom(insn.ea, False):
-            yield Characteristic("calls from"), ref
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(ref)
 
 
-def extract_function_indirect_call_characteristic_features(f, bb, insn):
-    """ extract indirect function calls (e.g., call eax or call dword ptr [edx+4])
-        does not include calls like => call ds:dword_ABD4974
+def extract_function_indirect_call_characteristic_features(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
+    """extract indirect function calls (e.g., call eax or call dword ptr [edx+4])
+    does not include calls like => call ds:dword_ABD4974
 
-        most relevant at the function or basic block scope;
-        however, its most efficient to extract at the instruction scope
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
+    most relevant at the function or basic block scope;
+    however, its most efficient to extract at the instruction scope
     """
+    insn: idaapi.insn_t = ih.inner
+
     if idaapi.is_call_insn(insn) and idc.get_operand_type(insn.ea, 0) in (idc.o_reg, idc.o_phrase, idc.o_displ):
-        yield Characteristic("indirect call"), insn.ea
+        yield Characteristic("indirect call"), ih.address
 
 
-def extract_features(f, bb, insn):
-    """ extract instruction features
-
-        args:
-            f (IDA func_t)
-            bb (IDA BasicBlock)
-            insn (IDA insn_t)
-    """
+def extract_features(f: FunctionHandle, bbh: BBHandle, insn: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """extract instruction features"""
     for inst_handler in INSTRUCTION_HANDLERS:
-        for (feature, ea) in inst_handler(f, bb, insn):
+        for feature, ea in inst_handler(f, bbh, insn):
             yield feature, ea
 
 
@@ -356,26 +500,10 @@ INSTRUCTION_HANDLERS = (
     extract_insn_offset_features,
     extract_insn_nzxor_characteristic_features,
     extract_insn_mnemonic_features,
+    extract_insn_obfs_call_plus_5_characteristic_features,
     extract_insn_peb_access_characteristic_features,
     extract_insn_cross_section_cflow,
     extract_insn_segment_access_features,
     extract_function_calls_from,
     extract_function_indirect_call_characteristic_features,
 )
-
-
-def main():
-    """ """
-    features = []
-    for f in capa.features.extractors.ida.helpers.get_functions(skip_thunks=True, skip_libs=True):
-        for bb in idaapi.FlowChart(f, flags=idaapi.FC_PREDS):
-            for insn in capa.features.extractors.ida.helpers.get_instructions_in_range(bb.start_ea, bb.end_ea):
-                features.extend(list(extract_features(f, bb, insn)))
-
-    import pprint
-
-    pprint.pprint(features)
-
-
-if __name__ == "__main__":
-    main()

capa/features/extractors/loops.py

@@ -1,19 +1,25 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-from networkx import nx
+import networkx
 from networkx.algorithms.components import strongly_connected_components
 
 
 def has_loop(edges, threshold=2):
-    """ check if a list of edges representing a directed graph contains a loop
+    """check if a list of edges representing a directed graph contains a loop
 
-        args:
-            edges: list of edge sets representing a directed graph i.e. [(1, 2), (2, 1)]
-            threshold: min number of nodes contained in loop
+    args:
+        edges: list of edge sets representing a directed graph i.e. [(1, 2), (2, 1)]
+        threshold: min number of nodes contained in loop
 
-        returns:
-            bool
+    returns:
+        bool
     """
-    g = nx.DiGraph()
+    g = networkx.DiGraph()
     g.add_edges_from(edges)
     return any(len(comp) >= threshold for comp in strongly_connected_components(g))

capa/features/extractors/null.py

@@ -0,0 +1,79 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Dict, List, Tuple
+from dataclasses import dataclass
+
+from capa.features.common import Feature
+from capa.features.address import NO_ADDRESS, Address
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle, FeatureExtractor
+
+
+@dataclass
+class InstructionFeatures:
+    features: List[Tuple[Address, Feature]]
+
+
+@dataclass
+class BasicBlockFeatures:
+    features: List[Tuple[Address, Feature]]
+    instructions: Dict[Address, InstructionFeatures]
+
+
+@dataclass
+class FunctionFeatures:
+    features: List[Tuple[Address, Feature]]
+    basic_blocks: Dict[Address, BasicBlockFeatures]
+
+
+@dataclass
+class NullFeatureExtractor(FeatureExtractor):
+    """
+    An extractor that extracts some user-provided features.
+
+    This is useful for testing, as we can provide expected values and see if matching works.
+    """
+
+    base_address: Address
+    global_features: List[Feature]
+    file_features: List[Tuple[Address, Feature]]
+    functions: Dict[Address, FunctionFeatures]
+
+    def get_base_address(self):
+        return self.base_address
+
+    def extract_global_features(self):
+        for feature in self.global_features:
+            yield feature, NO_ADDRESS
+
+    def extract_file_features(self):
+        for address, feature in self.file_features:
+            yield feature, address
+
+    def get_functions(self):
+        for address in sorted(self.functions.keys()):
+            yield FunctionHandle(address, None)
+
+    def extract_function_features(self, f):
+        for address, feature in self.functions[f.address].features:
+            yield feature, address
+
+    def get_basic_blocks(self, f):
+        for address in sorted(self.functions[f.address].basic_blocks.keys()):
+            yield BBHandle(address, None)
+
+    def extract_basic_block_features(self, f, bb):
+        for address, feature in self.functions[f.address].basic_blocks[bb.address].features:
+            yield feature, address
+
+    def get_instructions(self, f, bb):
+        for address in sorted(self.functions[f.address].basic_blocks[bb.address].instructions.keys()):
+            yield InsnHandle(address, None)
+
+    def extract_insn_features(self, f, bb, insn):
+        for address, feature in self.functions[f.address].basic_blocks[bb.address].instructions[insn.address].features:
+            yield feature, address

capa/features/extractors/pefile.py

@@ -0,0 +1,229 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import logging
+from pathlib import Path
+
+import pefile
+
+import capa.features.common
+import capa.features.extractors
+import capa.features.extractors.common
+import capa.features.extractors.helpers
+import capa.features.extractors.strings
+from capa.features.file import Export, Import, Section
+from capa.features.common import OS, ARCH_I386, FORMAT_PE, ARCH_AMD64, OS_WINDOWS, Arch, Format, Characteristic
+from capa.features.address import NO_ADDRESS, FileOffsetAddress, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import FeatureExtractor
+
+logger = logging.getLogger(__name__)
+
+
+def extract_file_embedded_pe(buf, **kwargs):
+    for offset, _ in capa.features.extractors.helpers.carve_pe(buf, 1):
+        yield Characteristic("embedded pe"), FileOffsetAddress(offset)
+
+
+def extract_file_export_names(pe, **kwargs):
+    base_address = pe.OPTIONAL_HEADER.ImageBase
+
+    if hasattr(pe, "DIRECTORY_ENTRY_EXPORT"):
+        for export in pe.DIRECTORY_ENTRY_EXPORT.symbols:
+            if not export.name:
+                continue
+            try:
+                name = export.name.partition(b"\x00")[0].decode("ascii")
+            except UnicodeDecodeError:
+                continue
+
+            if export.forwarder is None:
+                va = base_address + export.address
+                yield Export(name), AbsoluteVirtualAddress(va)
+
+            else:
+                try:
+                    forwarded_name = export.forwarder.partition(b"\x00")[0].decode("ascii")
+                except UnicodeDecodeError:
+                    continue
+                forwarded_name = capa.features.extractors.helpers.reformat_forwarded_export_name(forwarded_name)
+                va = base_address + export.address
+                yield Export(forwarded_name), AbsoluteVirtualAddress(va)
+                yield Characteristic("forwarded export"), AbsoluteVirtualAddress(va)
+
+
+def extract_file_import_names(pe, **kwargs):
+    """
+    extract imported function names
+    1. imports by ordinal:
+     - modulename.#ordinal
+    2. imports by name, results in two features to support importname-only matching:
+     - modulename.importname
+     - importname
+    """
+    if hasattr(pe, "DIRECTORY_ENTRY_IMPORT"):
+        for dll in pe.DIRECTORY_ENTRY_IMPORT:
+            try:
+                modname = dll.dll.partition(b"\x00")[0].decode("ascii")
+            except UnicodeDecodeError:
+                continue
+
+            # strip extension
+            modname = modname.rpartition(".")[0].lower()
+
+            for imp in dll.imports:
+                if imp.import_by_ordinal:
+                    impname = f"#{imp.ordinal}"
+                else:
+                    try:
+                        impname = imp.name.partition(b"\x00")[0].decode("ascii")
+                    except UnicodeDecodeError:
+                        continue
+
+                for name in capa.features.extractors.helpers.generate_symbols(modname, impname):
+                    yield Import(name), AbsoluteVirtualAddress(imp.address)
+
+
+def extract_file_section_names(pe, **kwargs):
+    base_address = pe.OPTIONAL_HEADER.ImageBase
+
+    for section in pe.sections:
+        try:
+            name = section.Name.partition(b"\x00")[0].decode("ascii")
+        except UnicodeDecodeError:
+            continue
+
+        yield Section(name), AbsoluteVirtualAddress(base_address + section.VirtualAddress)
+
+
+def extract_file_strings(buf, **kwargs):
+    yield from capa.features.extractors.common.extract_file_strings(buf)
+
+
+def extract_file_function_names(**kwargs):
+    """
+    extract the names of statically-linked library functions.
+    """
+    if False:
+        # using a `yield` here to force this to be a generator, not function.
+        yield NotImplementedError("pefile doesn't have library matching")
+    return
+
+
+def extract_file_os(**kwargs):
+    # assuming PE -> Windows
+    # though i suppose they're also used by UEFI
+    yield OS(OS_WINDOWS), NO_ADDRESS
+
+
+def extract_file_format(**kwargs):
+    yield Format(FORMAT_PE), NO_ADDRESS
+
+
+def extract_file_arch(pe, **kwargs):
+    if pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_I386"]:
+        yield Arch(ARCH_I386), NO_ADDRESS
+    elif pe.FILE_HEADER.Machine == pefile.MACHINE_TYPE["IMAGE_FILE_MACHINE_AMD64"]:
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+    else:
+        logger.warning("unsupported architecture: %s", pefile.MACHINE_TYPE[pe.FILE_HEADER.Machine])
+
+
+def extract_file_features(pe, buf):
+    """
+    extract file features from given workspace
+
+    args:
+      pe (pefile.PE): the parsed PE
+      buf: the raw sample bytes
+
+    yields:
+      Tuple[Feature, VA]: a feature and its location.
+    """
+
+    for file_handler in FILE_HANDLERS:
+        # file_handler: type: (pe, bytes) -> Iterable[Tuple[Feature, Address]]
+        for feature, va in file_handler(pe=pe, buf=buf):  # type: ignore
+            yield feature, va
+
+
+FILE_HANDLERS = (
+    extract_file_embedded_pe,
+    extract_file_export_names,
+    extract_file_import_names,
+    extract_file_section_names,
+    extract_file_strings,
+    extract_file_function_names,
+    extract_file_format,
+)
+
+
+def extract_global_features(pe, buf):
+    """
+    extract global features from given workspace
+
+    args:
+      pe (pefile.PE): the parsed PE
+      buf: the raw sample bytes
+
+    yields:
+      Tuple[Feature, VA]: a feature and its location.
+    """
+    for handler in GLOBAL_HANDLERS:
+        # file_handler: type: (pe, bytes) -> Iterable[Tuple[Feature, Address]]
+        for feature, va in handler(pe=pe, buf=buf):  # type: ignore
+            yield feature, va
+
+
+GLOBAL_HANDLERS = (
+    extract_file_os,
+    extract_file_arch,
+)
+
+
+class PefileFeatureExtractor(FeatureExtractor):
+    def __init__(self, path: Path):
+        super().__init__()
+        self.path: Path = path
+        self.pe = pefile.PE(str(path))
+
+    def get_base_address(self):
+        return AbsoluteVirtualAddress(self.pe.OPTIONAL_HEADER.ImageBase)
+
+    def extract_global_features(self):
+        buf = Path(self.path).read_bytes()
+
+        yield from extract_global_features(self.pe, buf)
+
+    def extract_file_features(self):
+        buf = Path(self.path).read_bytes()
+
+        yield from extract_file_features(self.pe, buf)
+
+    def get_functions(self):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def extract_function_features(self, f):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def get_basic_blocks(self, f):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def extract_basic_block_features(self, f, bb):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def get_instructions(self, f, bb):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def extract_insn_features(self, f, bb, insn):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def is_library_function(self, va):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")
+
+    def get_function_name(self, va):
+        raise NotImplementedError("PefileFeatureExtract can only be used to extract file features")

capa/features/extractors/strings.py

@@ -1,9 +1,15 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-#
-# strings code from FLOSS, https://github.com/fireeye/flare-floss
+# strings code from FLOSS, https://github.com/mandiant/flare-floss
 #
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
 import re
+import contextlib
 from collections import namedtuple
 
 ASCII_BYTE = r" !\"#\$%&\'\(\)\*\+,-\./0123456789:;<=>\?@ABCDEFGHIJKLMNOPQRSTUVWXYZ\[\]\^_`abcdefghijklmnopqrstuvwxyz\{\|\}\\\~\t".encode(
@@ -76,24 +82,5 @@ def extract_unicode_strings(buf, n=4):
         reg = b"((?:[%s]\x00){%d,})" % (ASCII_BYTE, n)
         r = re.compile(reg)
     for match in r.finditer(buf):
-        try:
+        with contextlib.suppress(UnicodeDecodeError):
             yield String(match.group().decode("utf-16"), match.start())
-        except UnicodeDecodeError:
-            pass
-
-
-def main():
-    import sys
-
-    with open(sys.argv[1], "rb") as f:
-        b = f.read()
-
-    for s in extract_ascii_strings(b):
-        print("0x{:x}: {:s}".format(s.offset, s.s))
-
-    for s in extract_unicode_strings(b):
-        print("0x{:x}: {:s}".format(s.offset, s.s))
-
-
-if __name__ == "__main__":
-    main()

capa/features/extractors/viv/__init__.py

@@ -1,79 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import types
-
-import viv_utils
-
-import file
-import insn
-import function
-import basicblock
-import capa.features.extractors
-import capa.features.extractors.viv.file
-import capa.features.extractors.viv.insn
-import capa.features.extractors.viv.function
-import capa.features.extractors.viv.basicblock
-from capa.features.extractors import FeatureExtractor
-
-__all__ = ["file", "function", "basicblock", "insn"]
-
-
-def get_va(self):
-    try:
-        # vivisect type
-        return self.va
-    except AttributeError:
-        pass
-
-    raise TypeError()
-
-
-def add_va_int_cast(o):
-    """
-    dynamically add a cast-to-int (`__int__`) method to the given object
-    that returns the value of the `.va` property.
-
-    this bit of skullduggery lets use cast viv-utils objects as ints.
-    the correct way of doing this is to update viv-utils (or subclass the objects here).
-    """
-    setattr(o, "__int__", types.MethodType(get_va, o, type(o)))
-    return o
-
-
-class VivisectFeatureExtractor(FeatureExtractor):
-    def __init__(self, vw, path):
-        super(VivisectFeatureExtractor, self).__init__()
-        self.vw = vw
-        self.path = path
-
-    def get_base_address(self):
-        # assume there is only one file loaded into the vw
-        return list(self.vw.filemeta.values())[0]["imagebase"]
-
-    def extract_file_features(self):
-        for feature, va in capa.features.extractors.viv.file.extract_features(self.vw, self.path):
-            yield feature, va
-
-    def get_functions(self):
-        for va in sorted(self.vw.getFunctions()):
-            yield add_va_int_cast(viv_utils.Function(self.vw, va))
-
-    def extract_function_features(self, f):
-        for feature, va in capa.features.extractors.viv.function.extract_features(f):
-            yield feature, va
-
-    def get_basic_blocks(self, f):
-        for bb in f.basic_blocks:
-            yield add_va_int_cast(bb)
-
-    def extract_basic_block_features(self, f, bb):
-        for feature, va in capa.features.extractors.viv.basicblock.extract_features(f, bb):
-            yield feature, va
-
-    def get_instructions(self, f, bb):
-        for insn in bb.instructions:
-            yield add_va_int_cast(insn)
-
-    def extract_insn_features(self, f, bb, insn):
-        for feature, va in capa.features.extractors.viv.insn.extract_features(f, bb, insn):
-            yield feature, va

capa/features/extractors/viv/basicblock.py

@@ -1,28 +1,37 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
 import string
 import struct
+from typing import Tuple, Iterator
 
 import envi
-import vivisect.const
+import envi.archs.i386.disasm
 
-from capa.features import Characteristic
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
 from capa.features.basicblock import BasicBlock
 from capa.features.extractors.helpers import MIN_STACKSTRING_LEN
+from capa.features.extractors.base_extractor import BBHandle, FunctionHandle
 
 
-def interface_extract_basic_block_XXX(f, bb):
+def interface_extract_basic_block_XXX(f: FunctionHandle, bb: BBHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     parse features from the given basic block.
 
     args:
-      f (viv_utils.Function): the function to process.
-      bb (viv_utils.BasicBlock): the basic block to process.
+      f: the function to process.
+      bb: the basic block to process.
 
     yields:
-      (Feature, int): the feature and the address at which its found.
+      (Feature, Address): the feature and the address at which its found.
     """
-    yield NotImplementedError("feature"), NotImplementedError("virtual address")
+    raise NotImplementedError
 
 
 def _bb_has_tight_loop(f, bb):
@@ -31,17 +40,17 @@ def _bb_has_tight_loop(f, bb):
     """
     if len(bb.instructions) > 0:
         for bva, bflags in bb.instructions[-1].getBranches():
-            if bflags & vivisect.envi.BR_COND:
+            if bflags & envi.BR_COND:
                 if bva == bb.va:
                     return True
 
     return False
 
 
-def extract_bb_tight_loop(f, bb):
-    """ check basic block for tight loop indicators """
-    if _bb_has_tight_loop(f, bb):
-        yield Characteristic("tight loop"), bb.va
+def extract_bb_tight_loop(f: FunctionHandle, bb: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """check basic block for tight loop indicators"""
+    if _bb_has_tight_loop(f, bb.inner):
+        yield Characteristic("tight loop"), bb.address
 
 
 def _bb_has_stackstring(f, bb):
@@ -61,13 +70,13 @@ def _bb_has_stackstring(f, bb):
     return False
 
 
-def extract_stackstring(f, bb):
-    """ check basic block for stackstring indicators """
-    if _bb_has_stackstring(f, bb):
-        yield Characteristic("stack string"), bb.va
+def extract_stackstring(f: FunctionHandle, bb: BBHandle) -> Iterator[Tuple[Feature, Address]]:
+    """check basic block for stackstring indicators"""
+    if _bb_has_stackstring(f, bb.inner):
+        yield Characteristic("stack string"), bb.address
 
 
-def is_mov_imm_to_stack(instr):
+def is_mov_imm_to_stack(instr: envi.archs.i386.disasm.i386Opcode) -> bool:
     """
     Return if instruction moves immediate onto stack
     """
@@ -83,7 +92,6 @@ def is_mov_imm_to_stack(instr):
     if not src.isImmed():
         return False
 
-    # TODO what about 64-bit operands?
     if not isinstance(dst, envi.archs.i386.disasm.i386SibOper) and not isinstance(
         dst, envi.archs.i386.disasm.i386RegMemOper
     ):
@@ -99,7 +107,7 @@ def is_mov_imm_to_stack(instr):
     return True
 
 
-def get_printable_len(oper):
+def get_printable_len(oper: envi.archs.i386.disasm.i386ImmOper) -> int:
     """
     Return string length if all operand bytes are ascii or utf16-le printable
     """
@@ -111,23 +119,33 @@ def get_printable_len(oper):
         chars = struct.pack("<I", oper.imm)
     elif oper.tsize == 8:
         chars = struct.pack("<Q", oper.imm)
+    else:
+        raise ValueError(f"unexpected oper.tsize: {oper.tsize}")
+
     if is_printable_ascii(chars):
         return oper.tsize
-    if is_printable_utf16le(chars):
+    elif is_printable_utf16le(chars):
         return oper.tsize / 2
-    return 0
+    else:
+        return 0
 
 
-def is_printable_ascii(chars):
-    return all(ord(c) < 127 and c in string.printable for c in chars)
+def is_printable_ascii(chars: bytes) -> bool:
+    try:
+        chars_str = chars.decode("ascii")
+    except UnicodeDecodeError:
+        return False
+    else:
+        return all(c in string.printable for c in chars_str)
 
 
-def is_printable_utf16le(chars):
-    if all(c == "\x00" for c in chars[1::2]):
+def is_printable_utf16le(chars: bytes) -> bool:
+    if all(c == b"\x00" for c in chars[1::2]):
         return is_printable_ascii(chars[::2])
+    return False
 
 
-def extract_features(f, bb):
+def extract_features(f: FunctionHandle, bb: BBHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     extract features from the given basic block.
 
@@ -136,12 +154,12 @@ def extract_features(f, bb):
       bb (viv_utils.BasicBlock): the basic block to process.
 
     yields:
-      Feature, set[VA]: the features and their location found in this basic block.
+      Tuple[Feature, int]: the features and their location found in this basic block.
     """
-    yield BasicBlock(), bb.va
+    yield BasicBlock(), AbsoluteVirtualAddress(bb.inner.va)
     for bb_handler in BASIC_BLOCK_HANDLERS:
-        for feature, va in bb_handler(f, bb):
-            yield feature, va
+        for feature, addr in bb_handler(f, bb):
+            yield feature, addr
 
 
 BASIC_BLOCK_HANDLERS = (

capa/features/extractors/viv/extractor.py

@@ -0,0 +1,83 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+from typing import Any, Dict, List, Tuple, Iterator
+from pathlib import Path
+
+import viv_utils
+import viv_utils.flirt
+
+import capa.features.extractors.common
+import capa.features.extractors.viv.file
+import capa.features.extractors.viv.insn
+import capa.features.extractors.viv.global_
+import capa.features.extractors.viv.function
+import capa.features.extractors.viv.basicblock
+from capa.features.common import Feature
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle, FeatureExtractor
+
+logger = logging.getLogger(__name__)
+
+
+class VivisectFeatureExtractor(FeatureExtractor):
+    def __init__(self, vw, path: Path, os):
+        super().__init__()
+        self.vw = vw
+        self.path = path
+        self.buf = path.read_bytes()
+
+        # pre-compute these because we'll yield them at *every* scope.
+        self.global_features: List[Tuple[Feature, Address]] = []
+        self.global_features.extend(capa.features.extractors.viv.file.extract_file_format(self.buf))
+        self.global_features.extend(capa.features.extractors.common.extract_os(self.buf, os))
+        self.global_features.extend(capa.features.extractors.viv.global_.extract_arch(self.vw))
+
+    def get_base_address(self):
+        # assume there is only one file loaded into the vw
+        return AbsoluteVirtualAddress(list(self.vw.filemeta.values())[0]["imagebase"])
+
+    def extract_global_features(self):
+        yield from self.global_features
+
+    def extract_file_features(self):
+        yield from capa.features.extractors.viv.file.extract_features(self.vw, self.buf)
+
+    def get_functions(self) -> Iterator[FunctionHandle]:
+        cache: Dict[str, Any] = {}
+        for va in sorted(self.vw.getFunctions()):
+            yield FunctionHandle(
+                address=AbsoluteVirtualAddress(va), inner=viv_utils.Function(self.vw, va), ctx={"cache": cache}
+            )
+
+    def extract_function_features(self, fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.viv.function.extract_features(fh)
+
+    def get_basic_blocks(self, fh: FunctionHandle) -> Iterator[BBHandle]:
+        f: viv_utils.Function = fh.inner
+        for bb in f.basic_blocks:
+            yield BBHandle(address=AbsoluteVirtualAddress(bb.va), inner=bb)
+
+    def extract_basic_block_features(self, fh: FunctionHandle, bbh) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.viv.basicblock.extract_features(fh, bbh)
+
+    def get_instructions(self, fh: FunctionHandle, bbh: BBHandle) -> Iterator[InsnHandle]:
+        bb: viv_utils.BasicBlock = bbh.inner
+        for insn in bb.instructions:
+            yield InsnHandle(address=AbsoluteVirtualAddress(insn.va), inner=insn)
+
+    def extract_insn_features(
+        self, fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+    ) -> Iterator[Tuple[Feature, Address]]:
+        yield from capa.features.extractors.viv.insn.extract_features(fh, bbh, ih)
+
+    def is_library_function(self, addr):
+        return viv_utils.flirt.is_library_function(self.vw, addr)
+
+    def get_function_name(self, addr):
+        return viv_utils.get_function_name(self.vw, addr)

capa/features/extractors/viv/file.py

@@ -1,26 +1,62 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Tuple, Iterator
 
 import PE.carve as pe_carve  # vivisect PE
+import vivisect
+import viv_utils
+import viv_utils.flirt
 
+import capa.features.insn
+import capa.features.extractors.common
+import capa.features.extractors.helpers
 import capa.features.extractors.strings
-from capa.features import String, Characteristic
-from capa.features.file import Export, Import, Section
+from capa.features.file import Export, Import, Section, FunctionName
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address, FileOffsetAddress, AbsoluteVirtualAddress
 
 
-def extract_file_embedded_pe(vw, file_path):
-    with open(file_path, "rb") as f:
-        fbytes = f.read()
-
-    for offset, i in pe_carve.carve(fbytes, 1):
-        yield Characteristic("embedded pe"), offset
+def extract_file_embedded_pe(buf, **kwargs) -> Iterator[Tuple[Feature, Address]]:
+    for offset, _ in pe_carve.carve(buf, 1):
+        yield Characteristic("embedded pe"), FileOffsetAddress(offset)
 
 
-def extract_file_export_names(vw, file_path):
-    for va, etype, name, _ in vw.getExports():
-        yield Export(name), va
+def get_first_vw_filename(vw: vivisect.VivWorkspace):
+    # vivisect associates metadata with each file that its loaded into the workspace.
+    # capa only loads a single file into each workspace.
+    # so to access the metadata for the file in question, we can just take the first one.
+    # otherwise, we'd have to pass around the module name of the file we're analyzing,
+    # which is a pain.
+    #
+    # so this is a simplifying assumption.
+    return next(iter(vw.filemeta.keys()))
 
 
-def extract_file_import_names(vw, file_path):
+def extract_file_export_names(vw: vivisect.VivWorkspace, **kwargs) -> Iterator[Tuple[Feature, Address]]:
+    for va, _, name, _ in vw.getExports():
+        yield Export(name), AbsoluteVirtualAddress(va)
+
+    if vw.getMeta("Format") == "pe":
+        pe = vw.parsedbin
+        baseaddr = pe.IMAGE_NT_HEADERS.OptionalHeader.ImageBase
+        for rva, _, forwarded_name in vw.getFileMeta(get_first_vw_filename(vw), "forwarders"):
+            try:
+                forwarded_name = forwarded_name.partition(b"\x00")[0].decode("ascii")
+            except UnicodeDecodeError:
+                continue
+
+            forwarded_name = capa.features.extractors.helpers.reformat_forwarded_export_name(forwarded_name)
+            va = baseaddr + rva
+            yield Export(forwarded_name), AbsoluteVirtualAddress(va)
+            yield Characteristic("forwarded export"), AbsoluteVirtualAddress(va)
+
+
+def extract_file_import_names(vw, **kwargs) -> Iterator[Tuple[Feature, Address]]:
     """
     extract imported function names
     1. imports by ordinal:
@@ -31,18 +67,17 @@ def extract_file_import_names(vw, file_path):
     """
     for va, _, _, tinfo in vw.getImports():
         # vivisect source: tinfo = "%s.%s" % (libname, impname)
-        modname, impname = tinfo.split(".")
+        modname, impname = tinfo.split(".", 1)
         if is_viv_ord_impname(impname):
             # replace ord prefix with #
-            impname = "#%s" % impname[len("ord") :]
-            tinfo = "%s.%s" % (modname, impname)
-            yield Import(tinfo), va
-        else:
-            yield Import(tinfo), va
-            yield Import(impname), va
+            impname = "#" + impname[len("ord") :]
+
+        addr = AbsoluteVirtualAddress(va)
+        for name in capa.features.extractors.helpers.generate_symbols(modname, impname):
+            yield Import(name), addr
 
 
-def is_viv_ord_impname(impname):
+def is_viv_ord_impname(impname: str) -> bool:
     """
     return if import name matches vivisect's ordinal naming scheme `'ord%d' % ord`
     """
@@ -56,40 +91,51 @@ def is_viv_ord_impname(impname):
         return True
 
 
-def extract_file_section_names(vw, file_path):
+def extract_file_section_names(vw, **kwargs) -> Iterator[Tuple[Feature, Address]]:
     for va, _, segname, _ in vw.getSegments():
-        yield Section(segname), va
+        yield Section(segname), AbsoluteVirtualAddress(va)
 
 
-def extract_file_strings(vw, file_path):
+def extract_file_strings(buf, **kwargs) -> Iterator[Tuple[Feature, Address]]:
+    yield from capa.features.extractors.common.extract_file_strings(buf)
+
+
+def extract_file_function_names(vw, **kwargs) -> Iterator[Tuple[Feature, Address]]:
     """
-    extract ASCII and UTF-16 LE strings from file
+    extract the names of statically-linked library functions.
     """
-    with open(file_path, "rb") as f:
-        b = f.read()
-
-    for s in capa.features.extractors.strings.extract_ascii_strings(b):
-        yield String(s.s), s.offset
-
-    for s in capa.features.extractors.strings.extract_unicode_strings(b):
-        yield String(s.s), s.offset
+    for va in sorted(vw.getFunctions()):
+        addr = AbsoluteVirtualAddress(va)
+        if viv_utils.flirt.is_library_function(vw, va):
+            name = viv_utils.get_function_name(vw, va)
+            yield FunctionName(name), addr
+            if name.startswith("_"):
+                # some linkers may prefix linked routines with a `_` to avoid name collisions.
+                # extract features for both the mangled and un-mangled representations.
+                # e.g. `_fwrite` -> `fwrite`
+                # see: https://stackoverflow.com/a/2628384/87207
+                yield FunctionName(name[1:]), addr
 
 
-def extract_features(vw, file_path):
+def extract_file_format(buf, **kwargs) -> Iterator[Tuple[Feature, Address]]:
+    yield from capa.features.extractors.common.extract_format(buf)
+
+
+def extract_features(vw, buf: bytes) -> Iterator[Tuple[Feature, Address]]:
     """
     extract file features from given workspace
 
     args:
       vw (vivisect.VivWorkspace): the vivisect workspace
-      file_path: path to the input file
+      buf: the raw input file bytes
 
     yields:
-      Tuple[Feature, VA]: a feature and its location.
+      Tuple[Feature, Address]: a feature and its location.
     """
 
     for file_handler in FILE_HANDLERS:
-        for feature, va in file_handler(vw, file_path):
-            yield feature, va
+        for feature, addr in file_handler(vw=vw, buf=buf):  # type: ignore
+            yield feature, addr
 
 
 FILE_HANDLERS = (
@@ -98,4 +144,6 @@ FILE_HANDLERS = (
     extract_file_import_names,
     extract_file_section_names,
     extract_file_strings,
+    extract_file_function_names,
+    extract_file_format,
 )

capa/features/extractors/viv/function.py

@@ -1,97 +1,110 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Tuple, Iterator
 
+import envi
+import viv_utils
 import vivisect.const
 
-from capa.features import Characteristic
+from capa.features.file import FunctionName
+from capa.features.common import Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
 from capa.features.extractors import loops
+from capa.features.extractors.elf import SymTab
+from capa.features.extractors.base_extractor import FunctionHandle
 
 
-def interface_extract_function_XXX(f):
+def interface_extract_function_XXX(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     parse features from the given function.
 
     args:
-      f (viv_utils.Function): the function to process.
+      f: the function to process.
 
     yields:
-      (Feature, int): the feature and the address at which its found.
+      (Feature, Address): the feature and the address at which its found.
     """
-    yield NotImplementedError("feature"), NotImplementedError("virtual address")
+    raise NotImplementedError
 
 
-def get_switches(vw):
-    """
-    caching accessor to vivisect workspace switch constructs.
-    """
-    if "switches" in vw.metadata:
-        return vw.metadata["switches"]
-    else:
-        # addresses of switches in the program
-        switches = set()
+def extract_function_symtab_names(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+    if fh.inner.vw.metadata["Format"] == "elf":
+        # the file's symbol table gets added to the metadata of the vivisect workspace.
+        # this is in order to eliminate the computational overhead of refetching symtab each time.
+        if "symtab" not in fh.ctx["cache"]:
+            try:
+                fh.ctx["cache"]["symtab"] = SymTab.from_viv(fh.inner.vw.parsedbin)
+            except Exception:
+                fh.ctx["cache"]["symtab"] = None
 
-        for case_va, _ in filter(lambda t: "case" in t[1], vw.getNames()):
-            # assume that the xref to a case location is a switch construct
-            for switch_va, _, _, _ in vw.getXrefsTo(case_va):
-                switches.add(switch_va)
+        symtab = fh.ctx["cache"]["symtab"]
+        if symtab:
+            for symbol in symtab.get_symbols():
+                sym_name = symtab.get_name(symbol)
+                sym_value = symbol.value
+                sym_info = symbol.info
 
-        vw.metadata["switches"] = switches
-        return switches
+                STT_FUNC = 0x2
+                if sym_value == fh.address and sym_info & STT_FUNC != 0:
+                    yield FunctionName(sym_name), fh.address
 
 
-def get_functions_with_switch(vw):
-    if "functions_with_switch" in vw.metadata:
-        return vw.metadata["functions_with_switch"]
-    else:
-        functions = set()
-        for switch in get_switches(vw):
-            functions.add(vw.getFunction(switch))
-        vw.metadata["functions_with_switch"] = functions
-        return functions
-
-
-def extract_function_switch(f):
-    """
-    parse if a function contains a switch statement based on location names
-    method can be optimized
-    """
-    if f.va in get_functions_with_switch(f.vw):
-        yield Characteristic("switch"), f.va
-
-
-def extract_function_calls_to(f):
+def extract_function_calls_to(fhandle: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
+    f: viv_utils.Function = fhandle.inner
     for src, _, _, _ in f.vw.getXrefsTo(f.va, rtype=vivisect.const.REF_CODE):
-        yield Characteristic("calls to"), src
+        yield Characteristic("calls to"), AbsoluteVirtualAddress(src)
 
 
-def extract_function_loop(f):
+def extract_function_loop(fhandle: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     parse if a function has a loop
     """
+    f: viv_utils.Function = fhandle.inner
+
     edges = []
 
     for bb in f.basic_blocks:
         if len(bb.instructions) > 0:
             for bva, bflags in bb.instructions[-1].getBranches():
-                if bflags & vivisect.envi.BR_COND or bflags & vivisect.envi.BR_FALL or bflags & vivisect.envi.BR_TABLE:
+                if bva is None:
+                    # vivisect may be unable to recover the call target, e.g. on dynamic calls like `call esi`
+                    # for this bva is None, and we don't want to add it for loop detection, ref: vivisect#574
+                    continue
+                # vivisect does not set branch flags for non-conditional jmp so add explicit check
+                if (
+                    bflags & envi.BR_COND
+                    or bflags & envi.BR_FALL
+                    or bflags & envi.BR_TABLE
+                    or bb.instructions[-1].mnem == "jmp"
+                ):
                     edges.append((bb.va, bva))
 
     if edges and loops.has_loop(edges):
-        yield Characteristic("loop"), f.va
+        yield Characteristic("loop"), fhandle.address
 
 
-def extract_features(f):
+def extract_features(fh: FunctionHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     extract features from the given function.
 
     args:
-      f (viv_utils.Function): the function from which to extract features
+      fh: the function handle from which to extract features
 
     yields:
-      Feature, set[VA]: the features and their location found in this function.
+      Tuple[Feature, int]: the features and their location found in this function.
     """
     for func_handler in FUNCTION_HANDLERS:
-        for feature, va in func_handler(f):
-            yield feature, va
+        for feature, addr in func_handler(fh):
+            yield feature, addr
 
 
-FUNCTION_HANDLERS = (extract_function_switch, extract_function_calls_to, extract_function_loop)
+FUNCTION_HANDLERS = (
+    extract_function_symtab_names,
+    extract_function_calls_to,
+    extract_function_loop,
+)

capa/features/extractors/viv/global_.py

@@ -0,0 +1,31 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+from typing import Tuple, Iterator
+
+from capa.features.common import ARCH_I386, ARCH_AMD64, Arch, Feature
+from capa.features.address import NO_ADDRESS, Address
+
+logger = logging.getLogger(__name__)
+
+
+def extract_arch(vw) -> Iterator[Tuple[Feature, Address]]:
+    arch = vw.getMeta("Architecture")
+    if arch == "amd64":
+        yield Arch(ARCH_AMD64), NO_ADDRESS
+
+    elif arch == "i386":
+        yield Arch(ARCH_I386), NO_ADDRESS
+
+    else:
+        # we likely end up here:
+        #  1. handling a new architecture (e.g. aarch64)
+        #
+        # for (1), this logic will need to be updated as the format is implemented.
+        logger.debug("unsupported architecture: %s", vw.arch.__class__.__name__)
+        return

capa/features/extractors/viv/helpers.py

@@ -0,0 +1,23 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import Optional
+
+from vivisect import VivWorkspace
+from vivisect.const import XR_TO, REF_CODE
+
+
+def get_coderef_from(vw: VivWorkspace, va: int) -> Optional[int]:
+    """
+    return first code `tova` whose origin is the specified va
+    return None if no code reference is found
+    """
+    xrefs = vw.getXrefsFrom(va, REF_CODE)
+    if len(xrefs) > 0:
+        return xrefs[0][XR_TO]
+    else:
+        return None

capa/features/extractors/viv/indirect_calls.py

@@ -1,11 +1,19 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
 import collections
+from typing import Set, List, Deque, Tuple, Optional
 
 import envi
 import vivisect.const
 import envi.archs.i386.disasm
 import envi.archs.amd64.disasm
+from vivisect import VivWorkspace
 
 # pull out consts for lookup performance
 i386RegOper = envi.archs.i386.disasm.i386RegOper
@@ -20,7 +28,7 @@ FAR_BRANCH_MASK = envi.BR_PROC | envi.BR_DEREF | envi.BR_ARCH
 DESTRUCTIVE_MNEMONICS = ("mov", "lea", "pop", "xor")
 
 
-def get_previous_instructions(vw, va):
+def get_previous_instructions(vw: VivWorkspace, va: int) -> List[int]:
     """
     collect the instructions that flow to the given address, local to the current function.
 
@@ -34,22 +42,24 @@ def get_previous_instructions(vw, va):
     ret = []
 
     # find the immediate prior instruction.
-    # ensure that it fallsthrough to this one.
+    # ensure that it falls through to this one.
     loc = vw.getPrevLocation(va, adjacent=True)
     if loc is not None:
-        # from vivisect.const:
-        # location: (L_VA, L_SIZE, L_LTYPE, L_TINFO)
-        (pva, _, ptype, pinfo) = vw.getPrevLocation(va, adjacent=True)
+        ploc = vw.getPrevLocation(va, adjacent=True)
+        if ploc is not None:
+            # from vivisect.const:
+            # location: (L_VA, L_SIZE, L_LTYPE, L_TINFO)
+            (pva, _, ptype, pinfo) = ploc
 
-        if ptype == LOC_OP and not (pinfo & IF_NOFALL):
-            ret.append(pva)
+            if ptype == LOC_OP and not (pinfo & IF_NOFALL):
+                ret.append(pva)
 
     # find any code refs, e.g. jmp, to this location.
     # ignore any calls.
     #
     # from vivisect.const:
     # xref: (XR_FROM, XR_TO, XR_RTYPE, XR_RFLAG)
-    for (xfrom, _, _, xflag) in vw.getXrefsTo(va, REF_CODE):
+    for xfrom, _, _, xflag in vw.getXrefsTo(va, REF_CODE):
         if (xflag & FAR_BRANCH_MASK) != 0:
             continue
         ret.append(xfrom)
@@ -61,7 +71,7 @@ class NotFoundError(Exception):
     pass
 
 
-def find_definition(vw, va, reg):
+def find_definition(vw: VivWorkspace, va: int, reg: int) -> Tuple[int, Optional[int]]:
     """
     scan backwards from the given address looking for assignments to the given register.
     if a constant, return that value.
@@ -77,8 +87,8 @@ def find_definition(vw, va, reg):
     raises:
       NotFoundError: when the definition cannot be found.
     """
-    q = collections.deque()
-    seen = set([])
+    q: Deque[int] = collections.deque()
+    seen: Set[int] = set()
 
     q.extend(get_previous_instructions(vw, va))
     while q:
@@ -122,14 +132,14 @@ def find_definition(vw, va, reg):
     raise NotFoundError()
 
 
-def is_indirect_call(vw, va, insn=None):
+def is_indirect_call(vw: VivWorkspace, va: int, insn: envi.Opcode) -> bool:
     if insn is None:
         insn = vw.parseOpcode(va)
 
-    return insn.mnem == "call" and isinstance(insn.opers[0], envi.archs.i386.disasm.i386RegOper)
+    return insn.mnem in ("call", "jmp") and isinstance(insn.opers[0], envi.archs.i386.disasm.i386RegOper)
 
 
-def resolve_indirect_call(vw, va, insn=None):
+def resolve_indirect_call(vw: VivWorkspace, va: int, insn: envi.Opcode) -> Tuple[int, Optional[int]]:
     """
     inspect the given indirect call instruction and attempt to resolve the target address.
 

capa/features/extractors/viv/insn.py

@@ -1,12 +1,29 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+from typing import List, Tuple, Callable, Iterator
 
+import envi
+import envi.exc
+import viv_utils
 import envi.memory
-import vivisect.const
+import viv_utils.flirt
+import envi.archs.i386.regs
+import envi.archs.amd64.regs
 import envi.archs.i386.disasm
+import envi.archs.amd64.disasm
 
 import capa.features.extractors.helpers
-from capa.features import MAX_BYTES_FEATURE_SIZE, Bytes, String, Characteristic
-from capa.features.insn import Number, Offset, Mnemonic
+import capa.features.extractors.viv.helpers
+from capa.features.insn import API, MAX_STRUCTURE_SIZE, Number, Offset, Mnemonic, OperandNumber, OperandOffset
+from capa.features.common import MAX_BYTES_FEATURE_SIZE, THUNK_CHAIN_DEPTH_DELTA, Bytes, String, Feature, Characteristic
+from capa.features.address import Address, AbsoluteVirtualAddress
+from capa.features.extractors.elf import SymTab
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle
 from capa.features.extractors.viv.indirect_calls import NotFoundError, resolve_indirect_call
 
 # security cookie checks may perform non-zeroing XORs, these are expected within a certain
@@ -14,70 +31,129 @@ from capa.features.extractors.viv.indirect_calls import NotFoundError, resolve_i
 SECURITY_COOKIE_BYTES_DELTA = 0x40
 
 
-def interface_extract_instruction_XXX(f, bb, insn):
+def interface_extract_instruction_XXX(
+    fh: FunctionHandle, bbh: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
     parse features from the given instruction.
 
     args:
-      f (viv_utils.Function): the function to process.
-      bb (viv_utils.BasicBlock): the basic block to process.
-      insn (vivisect...Instruction): the instruction to process.
+      fh: the function handle to process.
+      bbh: the basic block handle to process.
+      ih: the instruction handle to process.
 
     yields:
-      (Feature, int): the feature and the address at which its found.
+      (Feature, Address): the feature and the address at which its found.
     """
-    yield NotImplementedError("feature"), NotImplementedError("virtual address")
+    raise NotImplementedError
 
 
 def get_imports(vw):
     """
     caching accessor to vivisect workspace imports
     avoids performance issues in vivisect when collecting locations
+
+    returns: Dict[int, Tuple[str, str]]
     """
     if "imports" in vw.metadata:
         return vw.metadata["imports"]
     else:
-        imports = {p[0]: p[3] for p in vw.getImports()}
+        imports = {
+            p[0]: (p[3].rpartition(".")[0], p[3].replace(".ord", ".#").rpartition(".")[2]) for p in vw.getImports()
+        }
         vw.metadata["imports"] = imports
         return imports
 
 
-def extract_insn_api_features(f, bb, insn):
-    """parse API features from the given instruction."""
+def extract_insn_api_features(fh: FunctionHandle, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse API features from the given instruction.
 
-    # example:
-    #
-    #    call dword [0x00473038]
-
-    if insn.mnem != "call":
+    example:
+       call dword [0x00473038]
+    """
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+    if insn.mnem not in ("call", "jmp"):
         return
 
+    if insn.mnem == "jmp":
+        if f.vw.getFunctionMeta(f.va, "Thunk"):
+            return
+
     # traditional call via IAT
     if isinstance(insn.opers[0], envi.archs.i386.disasm.i386ImmMemOper):
         oper = insn.opers[0]
         target = oper.getOperAddr(insn)
 
         imports = get_imports(f.vw)
-        if target in imports.keys():
-            for feature, va in capa.features.extractors.helpers.generate_api_features(imports[target], insn.va):
-                yield feature, va
+        if target in imports:
+            dll, symbol = imports[target]
+            for name in capa.features.extractors.helpers.generate_symbols(dll, symbol):
+                yield API(name), ih.address
 
     # call via thunk on x86,
     # see 9324d1a8ae37a36ae560c37448c9705a at 0x407985
     #
-    # this is also how calls to internal functions may be decoded on x64.
+    # this is also how calls to internal functions may be decoded on x32 and x64.
     # see Lab21-01.exe_:0x140001178
-    elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386PcRelOper):
-        target = insn.opers[0].getOperValue(insn)
+    #
+    # follow chained thunks, e.g. in 82bf6347acf15e5d883715dc289d8a2b at 0x14005E0FF in
+    # 0x140059342 (viv) / 0x14005E0C0 (IDA)
+    # 14005E0FF call    j_ElfClearEventLogFileW (14005AAF8)
+    #   14005AAF8 jmp     ElfClearEventLogFileW (14005E196)
+    #     14005E196 jmp     cs:__imp_ElfClearEventLogFileW
 
-        try:
-            thunk = f.vw.getFunctionMeta(target, "Thunk")
-        except vivisect.exc.InvalidFunction:
+    elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386PcRelOper):
+        imports = get_imports(f.vw)
+        target = capa.features.extractors.viv.helpers.get_coderef_from(f.vw, insn.va)
+        if not target:
             return
-        else:
-            if thunk:
-                for feature, va in capa.features.extractors.helpers.generate_api_features(thunk, insn.va):
-                    yield feature, va
+
+        if f.vw.metadata["Format"] == "elf":
+            if "symtab" not in fh.ctx["cache"]:
+                # the symbol table gets stored as a function's attribute in order to avoid running
+                # this code everytime the call is made, thus preventing the computational overhead.
+                try:
+                    fh.ctx["cache"]["symtab"] = SymTab.from_viv(f.vw.parsedbin)
+                except Exception:
+                    fh.ctx["cache"]["symtab"] = None
+
+            symtab = fh.ctx["cache"]["symtab"]
+            if symtab:
+                for symbol in symtab.get_symbols():
+                    sym_name = symtab.get_name(symbol)
+                    sym_value = symbol.value
+                    sym_info = symbol.info
+
+                    STT_FUNC = 0x2
+                    if sym_value == target and sym_info & STT_FUNC != 0:
+                        yield API(sym_name), ih.address
+
+        if viv_utils.flirt.is_library_function(f.vw, target):
+            name = viv_utils.get_function_name(f.vw, target)
+            yield API(name), ih.address
+            if name.startswith("_"):
+                # some linkers may prefix linked routines with a `_` to avoid name collisions.
+                # extract features for both the mangled and un-mangled representations.
+                # e.g. `_fwrite` -> `fwrite`
+                # see: https://stackoverflow.com/a/2628384/87207
+                yield API(name[1:]), ih.address
+            return
+
+        for _ in range(THUNK_CHAIN_DEPTH_DELTA):
+            if target in imports:
+                dll, symbol = imports[target]
+                for name in capa.features.extractors.helpers.generate_symbols(dll, symbol):
+                    yield API(name), ih.address
+
+            # if jump leads to an ENDBRANCH instruction, skip it
+            if f.vw.getByteDef(target)[1].startswith(b"\xf3\x0f\x1e"):
+                target += 4
+
+            target = capa.features.extractors.viv.helpers.get_coderef_from(f.vw, target)
+            if not target:
+                return
 
     # call via import on x64
     # see Lab21-01.exe_:0x14000118C
@@ -86,9 +162,10 @@ def extract_insn_api_features(f, bb, insn):
         target = op.getOperAddr(insn)
 
         imports = get_imports(f.vw)
-        if target in imports.keys():
-            for feature, va in capa.features.extractors.helpers.generate_api_features(imports[target], insn.va):
-                yield feature, va
+        if target in imports:
+            dll, symbol = imports[target]
+            for name in capa.features.extractors.helpers.generate_symbols(dll, symbol):
+                yield API(name), ih.address
 
     elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386RegOper):
         try:
@@ -102,91 +179,148 @@ def extract_insn_api_features(f, bb, insn):
             return
 
         imports = get_imports(f.vw)
-        if target in imports.keys():
-            for feature, va in capa.features.extractors.helpers.generate_api_features(imports[target], insn.va):
-                yield feature, va
+        if target in imports:
+            dll, symbol = imports[target]
+            for name in capa.features.extractors.helpers.generate_symbols(dll, symbol):
+                yield API(name), ih.address
 
 
-def extract_insn_number_features(f, bb, insn):
-    """parse number features from the given instruction."""
-    # example:
-    #
-    #     push    3136B0h         ; dwControlCode
-    for oper in insn.opers:
-        # this is for both x32 and x64
-        if not isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
-            continue
+def derefs(vw, p):
+    """
+    recursively follow the given pointer, yielding the valid memory addresses along the way.
+    useful when you may have a pointer to string, or pointer to pointer to string, etc.
 
-        v = oper.getOperValue(oper)
-
-        if f.vw.probeMemory(v, 1, envi.memory.MM_READ):
-            # this is a valid address
-            # assume its not also a constant.
-            continue
-
-        if insn.mnem == "add" and insn.opers[0].isReg() and insn.opers[0].reg == envi.archs.i386.disasm.REG_ESP:
-            # skip things like:
-            #
-            #    .text:00401140                 call    sub_407E2B
-            #    .text:00401145                 add     esp, 0Ch
+    this is a "do what i mean" type of helper function.
+    """
+    depth = 0
+    while True:
+        if not vw.isValidPointer(p):
             return
 
-        yield Number(v), insn.va
+        yield p
+
+        if vw.isProbablyString(p) or vw.isProbablyUnicode(p):
+            # don't deref strings that coincidentally are pointers
+            return
+
+        try:
+            next = vw.readMemoryPtr(p)
+        except Exception:
+            # if not enough bytes can be read, such as end of the section.
+            # unfortunately, viv returns a plain old generic `Exception` for this.
+            return
+
+        # sanity: pointer points to self
+        if next == p:
+            return
+
+        # sanity: avoid chains of pointers that are unreasonably deep
+        depth += 1
+        if depth > 10:
+            return
+
+        p = next
 
 
-def extract_insn_bytes_features(f, bb, insn):
+def read_memory(vw, va: int, size: int) -> bytes:
+    # as documented in #176, vivisect will not readMemory() when the section is not marked readable.
+    #
+    # but here, we don't care about permissions.
+    # so, copy the viv implementation of readMemory and remove the permissions check.
+    #
+    # this is derived from:
+    #   https://github.com/vivisect/vivisect/blob/5eb4d237bddd4069449a6bc094d332ceed6f9a96/envi/memory.py#L453-L462
+    for mva, mmaxva, mmap, mbytes in vw._map_defs:
+        if va >= mva and va < mmaxva:
+            mva, msize, mperms, mfname = mmap
+            offset = va - mva
+            return mbytes[offset : offset + size]
+    raise envi.exc.SegmentationViolation(va)
+
+
+def read_bytes(vw, va: int) -> bytes:
+    """
+    read up to MAX_BYTES_FEATURE_SIZE from the given address.
+
+    raises:
+      envi.SegmentationViolation: if the given address is not valid.
+    """
+    segm = vw.getSegment(va)
+    if not segm:
+        raise envi.exc.SegmentationViolation(va)
+
+    segm_end = segm[0] + segm[1]
+    try:
+        # Do not read beyond the end of a segment
+        if va + MAX_BYTES_FEATURE_SIZE > segm_end:
+            return read_memory(vw, va, segm_end - va)
+        else:
+            return read_memory(vw, va, MAX_BYTES_FEATURE_SIZE)
+    except envi.exc.SegmentationViolation:
+        raise
+
+
+def extract_insn_bytes_features(fh: FunctionHandle, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     parse byte sequence features from the given instruction.
     example:
         #     push    offset iid_004118d4_IShellLinkA ; riid
     """
-    for oper in insn.opers:
-        if insn.mnem == "call":
-            # ignore call instructions
-            continue
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
 
+    if insn.mnem == "call":
+        return
+
+    for oper in insn.opers:
         if isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
             v = oper.getOperValue(oper)
         elif isinstance(oper, envi.archs.i386.disasm.i386RegMemOper):
             # handle case like:
             #   movzx   ecx, ds:byte_423258[eax]
             v = oper.disp
+        elif isinstance(oper, envi.archs.i386.disasm.i386SibOper):
+            # like 0x401000 in `mov eax, 0x401000[2 * ebx]`
+            v = oper.imm
         elif isinstance(oper, envi.archs.amd64.disasm.Amd64RipRelOper):
             # see: Lab21-01.exe_:0x1400010D3
             v = oper.getOperAddr(insn)
         else:
             continue
 
-        segm = f.vw.getSegment(v)
-        if not segm:
-            continue
+        for vv in derefs(f.vw, v):
+            try:
+                buf = read_bytes(f.vw, vv)
+            except envi.exc.SegmentationViolation:
+                continue
 
-        segm_end = segm[0] + segm[1]
-        try:
-            # Do not read beyond the end of a segment
-            if v + MAX_BYTES_FEATURE_SIZE > segm_end:
-                extracted_bytes = f.vw.readMemory(v, segm_end - v)
-            else:
-                extracted_bytes = f.vw.readMemory(v, MAX_BYTES_FEATURE_SIZE)
-        except envi.SegmentationViolation:
-            pass
-        else:
-            if not capa.features.extractors.helpers.all_zeros(extracted_bytes):
-                yield Bytes(extracted_bytes), insn.va
+            if capa.features.extractors.helpers.all_zeros(buf):
+                continue
+
+            if f.vw.isProbablyString(vv) or f.vw.isProbablyUnicode(vv):
+                # don't extract byte features for obvious strings
+                continue
+
+            yield Bytes(buf), ih.address
 
 
-def read_string(vw, offset):
+def read_string(vw, offset: int) -> str:
     try:
         alen = vw.detectString(offset)
-    except envi.SegmentationViolation:
+    except envi.exc.SegmentationViolation:
         pass
     else:
         if alen > 0:
-            return vw.readMemory(offset, alen).decode("utf-8")
+            buf = read_memory(vw, offset, alen)
+            if b"\x00" in buf:
+                # account for bug #1271.
+                # remove when vivisect is fixed.
+                buf = buf.partition(b"\x00")[0]
+            return buf.decode("utf-8")
 
     try:
         ulen = vw.detectUnicode(offset)
-    except envi.SegmentationViolation:
+    except envi.exc.SegmentationViolation:
         pass
     except IndexError:
         # potential vivisect bug detecting Unicode at segment end
@@ -197,67 +331,28 @@ def read_string(vw, offset):
                 # vivisect seems to mis-detect the end unicode strings
                 # off by one, too short
                 ulen += 1
-            return vw.readMemory(offset, ulen).decode("utf-16")
+            else:
+                # vivisect seems to mis-detect the end unicode strings
+                # off by two, too short
+                ulen += 2
+            # partition to account for bug #1271.
+            # remove when vivisect is fixed.
+            return read_memory(vw, offset, ulen).decode("utf-16").partition("\x00")[0]
 
     raise ValueError("not a string", offset)
 
 
-def extract_insn_string_features(f, bb, insn):
-    """parse string features from the given instruction."""
-    # example:
-    #
-    #     push    offset aAcr     ; "ACR  > "
-    for oper in insn.opers:
-        if isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
-            v = oper.getOperValue(oper)
-        elif isinstance(oper, envi.archs.amd64.disasm.Amd64RipRelOper):
-            v = oper.getOperAddr(insn)
-        else:
-            continue
-
-        try:
-            s = read_string(f.vw, v)
-        except ValueError:
-            continue
-        else:
-            yield String(s.rstrip("\x00")), insn.va
-
-
-def extract_insn_offset_features(f, bb, insn):
-    """parse structure offset features from the given instruction."""
-    # example:
-    #
-    #     .text:0040112F    cmp     [esi+4], ebx
-    for oper in insn.opers:
-        # this is for both x32 and x64
-        if not isinstance(oper, envi.archs.i386.disasm.i386RegMemOper):
-            continue
-
-        if oper.reg == envi.archs.i386.disasm.REG_ESP:
-            continue
-
-        if oper.reg == envi.archs.i386.disasm.REG_EBP:
-            continue
-
-        # TODO: do x64 support for real.
-        if oper.reg == envi.archs.amd64.disasm.REG_RBP:
-            continue
-
-        yield Offset(oper.disp), insn.va
-
-
-def is_security_cookie(f, bb, insn):
+def is_security_cookie(f, bb, insn) -> bool:
     """
     check if an instruction is related to security cookie checks
     """
     # security cookie check should use SP or BP
     oper = insn.opers[1]
     if oper.isReg() and oper.reg not in [
-        envi.archs.i386.disasm.REG_ESP,
-        envi.archs.i386.disasm.REG_EBP,
-        # TODO: do x64 support for real.
-        envi.archs.amd64.disasm.REG_RBP,
-        envi.archs.amd64.disasm.REG_RSP,
+        envi.archs.i386.regs.REG_ESP,
+        envi.archs.i386.regs.REG_EBP,
+        envi.archs.amd64.regs.REG_RBP,
+        envi.archs.amd64.regs.REG_RSP,
     ]:
         return False
 
@@ -274,12 +369,18 @@ def is_security_cookie(f, bb, insn):
     return False
 
 
-def extract_insn_nzxor_characteristic_features(f, bb, insn):
+def extract_insn_nzxor_characteristic_features(
+    fh: FunctionHandle, bbhandle: BBHandle, ih: InsnHandle
+) -> Iterator[Tuple[Feature, Address]]:
     """
     parse non-zeroing XOR instruction from the given instruction.
     ignore expected non-zeroing XORs, e.g. security cookies.
     """
-    if insn.mnem != "xor":
+    insn: envi.Opcode = ih.inner
+    bb: viv_utils.BasicBlock = bbhandle.inner
+    f: viv_utils.Function = fh.inner
+
+    if insn.mnem not in ("xor", "xorpd", "xorps", "pxor"):
         return
 
     if insn.opers[0] == insn.opers[1]:
@@ -288,24 +389,44 @@ def extract_insn_nzxor_characteristic_features(f, bb, insn):
     if is_security_cookie(f, bb, insn):
         return
 
-    yield Characteristic("nzxor"), insn.va
+    yield Characteristic("nzxor"), ih.address
 
 
-def extract_insn_mnemonic_features(f, bb, insn):
+def extract_insn_mnemonic_features(f, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """parse mnemonic features from the given instruction."""
-    yield Mnemonic(insn.mnem), insn.va
+    yield Mnemonic(ih.inner.mnem), ih.address
 
 
-def extract_insn_peb_access_characteristic_features(f, bb, insn):
+def extract_insn_obfs_call_plus_5_characteristic_features(f, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """
+    parse call $+5 instruction from the given instruction.
+    """
+    insn: envi.Opcode = ih.inner
+
+    if insn.mnem != "call":
+        return
+
+    if isinstance(insn.opers[0], envi.archs.i386.disasm.i386PcRelOper):
+        if insn.va + 5 == insn.opers[0].getOperValue(insn):
+            yield Characteristic("call $+5"), ih.address
+
+    if isinstance(insn.opers[0], (envi.archs.i386.disasm.i386ImmMemOper, envi.archs.amd64.disasm.Amd64RipRelOper)):
+        if insn.va + 5 == insn.opers[0].getOperAddr(insn):
+            yield Characteristic("call $+5"), ih.address
+
+
+def extract_insn_peb_access_characteristic_features(f, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     parse peb access from the given function. fs:[0x30] on x86, gs:[0x60] on x64
     """
-    # TODO handle where fs/gs are loaded into a register or onto the stack and used later
+    insn: envi.Opcode = ih.inner
 
     if insn.mnem not in ["push", "mov"]:
         return
 
-    if "fs" in insn.getPrefixName():
+    prefix = insn.getPrefixName()
+
+    if "fs" in prefix:
         for oper in insn.opers:
             # examples
             #
@@ -317,29 +438,33 @@ def extract_insn_peb_access_characteristic_features(f, bb, insn):
             if (isinstance(oper, envi.archs.i386.disasm.i386RegMemOper) and oper.disp == 0x30) or (
                 isinstance(oper, envi.archs.i386.disasm.i386ImmMemOper) and oper.imm == 0x30
             ):
-                yield Characteristic("peb access"), insn.va
-    elif "gs" in insn.getPrefixName():
+                yield Characteristic("peb access"), ih.address
+    elif "gs" in prefix:
         for oper in insn.opers:
-            if (isinstance(oper, envi.archs.amd64.disasm.i386RegMemOper) and oper.disp == 0x60) or (
-                isinstance(oper, envi.archs.amd64.disasm.i386ImmMemOper) and oper.imm == 0x60
+            if (
+                (isinstance(oper, envi.archs.amd64.disasm.i386RegMemOper) and oper.disp == 0x60)
+                or (isinstance(oper, envi.archs.amd64.disasm.i386SibOper) and oper.imm == 0x60)
+                or (isinstance(oper, envi.archs.amd64.disasm.i386ImmMemOper) and oper.imm == 0x60)
             ):
-                yield Characteristic("peb access"), insn.va
+                yield Characteristic("peb access"), ih.address
     else:
         pass
 
 
-def extract_insn_segment_access_features(f, bb, insn):
-    """ parse the instruction for access to fs or gs """
+def extract_insn_segment_access_features(f, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    """parse the instruction for access to fs or gs"""
+    insn: envi.Opcode = ih.inner
+
     prefix = insn.getPrefixName()
 
     if prefix == "fs":
-        yield Characteristic("fs access"), insn.va
+        yield Characteristic("fs access"), ih.address
 
     if prefix == "gs":
-        yield Characteristic("gs access"), insn.va
+        yield Characteristic("gs access"), ih.address
 
 
-def get_section(vw, va):
+def get_section(vw, va: int):
     for start, length, _, __ in vw.getMemoryMaps():
         if start <= va < start + length:
             return start
@@ -347,11 +472,18 @@ def get_section(vw, va):
     raise KeyError(va)
 
 
-def extract_insn_cross_section_cflow(f, bb, insn):
+def extract_insn_cross_section_cflow(fh: FunctionHandle, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     inspect the instruction for a CALL or JMP that crosses section boundaries.
     """
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+
     for va, flags in insn.getBranches():
+        if va is None:
+            # va may be none for dynamic branches that haven't been resolved, such as `jmp eax`.
+            continue
+
         if flags & envi.BR_FALL:
             continue
 
@@ -373,7 +505,7 @@ def extract_insn_cross_section_cflow(f, bb, insn):
                     continue
 
             if get_section(f.vw, insn.va) != get_section(f.vw, va):
-                yield Characteristic("cross section flow"), insn.va
+                yield Characteristic("cross section flow"), ih.address
 
         except KeyError:
             continue
@@ -381,7 +513,10 @@ def extract_insn_cross_section_cflow(f, bb, insn):
 
 # this is a feature that's most relevant at the function scope,
 # however, its most efficient to extract at the instruction scope.
-def extract_function_calls_from(f, bb, insn):
+def extract_function_calls_from(fh: FunctionHandle, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+
     if insn.mnem != "call":
         return
 
@@ -391,7 +526,8 @@ def extract_function_calls_from(f, bb, insn):
     if isinstance(insn.opers[0], envi.archs.i386.disasm.i386ImmMemOper):
         oper = insn.opers[0]
         target = oper.getOperAddr(insn)
-        yield Characteristic("calls from"), target
+        if target >= 0:
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(target)
 
     # call via thunk on x86,
     # see 9324d1a8ae37a36ae560c37448c9705a at 0x407985
@@ -400,43 +536,192 @@ def extract_function_calls_from(f, bb, insn):
     # see Lab21-01.exe_:0x140001178
     elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386PcRelOper):
         target = insn.opers[0].getOperValue(insn)
-        yield Characteristic("calls from"), target
+        if target >= 0:
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(target)
 
     # call via IAT, x64
     elif isinstance(insn.opers[0], envi.archs.amd64.disasm.Amd64RipRelOper):
         op = insn.opers[0]
         target = op.getOperAddr(insn)
-        yield Characteristic("calls from"), target
+        if target >= 0:
+            yield Characteristic("calls from"), AbsoluteVirtualAddress(target)
 
     if target and target == f.va:
         # if we found a jump target and it's the function address
         # mark as recursive
-        yield Characteristic("recursive call"), target
+        yield Characteristic("recursive call"), AbsoluteVirtualAddress(target)
 
 
 # this is a feature that's most relevant at the function or basic block scope,
 # however, its most efficient to extract at the instruction scope.
-def extract_function_indirect_call_characteristic_features(f, bb, insn):
+def extract_function_indirect_call_characteristic_features(f, bb, ih: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
     """
     extract indirect function call characteristic (e.g., call eax or call dword ptr [edx+4])
     does not include calls like => call ds:dword_ABD4974
     """
+    insn: envi.Opcode = ih.inner
+
     if insn.mnem != "call":
         return
 
     # Checks below work for x86 and x64
     if isinstance(insn.opers[0], envi.archs.i386.disasm.i386RegOper):
         # call edx
-        yield Characteristic("indirect call"), insn.va
+        yield Characteristic("indirect call"), ih.address
     elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386RegMemOper):
         # call dword ptr [eax+50h]
-        yield Characteristic("indirect call"), insn.va
+        yield Characteristic("indirect call"), ih.address
     elif isinstance(insn.opers[0], envi.archs.i386.disasm.i386SibOper):
         # call qword ptr [rsp+78h]
-        yield Characteristic("indirect call"), insn.va
+        yield Characteristic("indirect call"), ih.address
 
 
-def extract_features(f, bb, insn):
+def extract_op_number_features(
+    fh: FunctionHandle, bb, ih: InsnHandle, i, oper: envi.Operand
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse number features from the given operand.
+
+    example:
+        push    3136B0h         ; dwControlCode
+    """
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+
+    # this is for both x32 and x64
+    if not isinstance(oper, (envi.archs.i386.disasm.i386ImmOper, envi.archs.i386.disasm.i386ImmMemOper)):
+        return
+
+    if isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
+        v = oper.getOperValue(oper)
+    else:
+        v = oper.getOperAddr(oper)
+
+    if f.vw.probeMemory(v, 1, envi.memory.MM_READ):
+        # this is a valid address
+        # assume its not also a constant.
+        return
+
+    if insn.mnem == "add" and insn.opers[0].isReg() and insn.opers[0].reg == envi.archs.i386.regs.REG_ESP:
+        # skip things like:
+        #
+        #    .text:00401140                 call    sub_407E2B
+        #    .text:00401145                 add     esp, 0Ch
+        return
+
+    yield Number(v), ih.address
+    yield OperandNumber(i, v), ih.address
+
+    if insn.mnem == "add" and 0 < v < MAX_STRUCTURE_SIZE and isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
+        # for pattern like:
+        #
+        #     add eax, 0x10
+        #
+        # assume 0x10 is also an offset (imagine eax is a pointer).
+        yield Offset(v), ih.address
+        yield OperandOffset(i, v), ih.address
+
+
+def extract_op_offset_features(
+    fh: FunctionHandle, bb, ih: InsnHandle, i, oper: envi.Operand
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse structure offset features from the given operand."""
+    # example:
+    #
+    #     .text:0040112F    cmp     [esi+4], ebx
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+
+    # this is for both x32 and x64
+    # like [esi + 4]
+    #       reg   ^
+    #             disp
+    if isinstance(oper, envi.archs.i386.disasm.i386RegMemOper):
+        if oper.reg == envi.archs.i386.regs.REG_ESP:
+            return
+
+        if oper.reg == envi.archs.i386.regs.REG_EBP:
+            return
+
+        if oper.reg == envi.archs.amd64.regs.REG_RBP:
+            return
+
+        # viv already decodes offsets as signed
+        v = oper.disp
+
+        yield Offset(v), ih.address
+        yield OperandOffset(i, v), ih.address
+
+        if insn.mnem == "lea" and i == 1 and not f.vw.probeMemory(v, 1, envi.memory.MM_READ):
+            # for pattern like:
+            #
+            #     lea eax, [ebx + 1]
+            #
+            # assume 1 is also an offset (imagine ebx is a zero register).
+            yield Number(v), ih.address
+            yield OperandNumber(i, v), ih.address
+
+    # like: [esi + ecx + 16384]
+    #        reg   ^     ^
+    #              index ^
+    #                    disp
+    elif isinstance(oper, envi.archs.i386.disasm.i386SibOper):
+        # viv already decodes offsets as signed
+        v = oper.disp
+
+        yield Offset(v), ih.address
+        yield OperandOffset(i, v), ih.address
+
+
+def extract_op_string_features(
+    fh: FunctionHandle, bb, ih: InsnHandle, i, oper: envi.Operand
+) -> Iterator[Tuple[Feature, Address]]:
+    """parse string features from the given operand."""
+    # example:
+    #
+    #     push    offset aAcr     ; "ACR  > "
+    insn: envi.Opcode = ih.inner
+    f: viv_utils.Function = fh.inner
+
+    if isinstance(oper, envi.archs.i386.disasm.i386ImmOper):
+        v = oper.getOperValue(oper)
+    elif isinstance(oper, envi.archs.i386.disasm.i386ImmMemOper):
+        # like 0x10056CB4 in `lea eax, dword [0x10056CB4]`
+        v = oper.imm
+    elif isinstance(oper, envi.archs.i386.disasm.i386SibOper):
+        # like 0x401000 in `mov eax, 0x401000[2 * ebx]`
+        v = oper.imm
+    elif isinstance(oper, envi.archs.amd64.disasm.Amd64RipRelOper):
+        v = oper.getOperAddr(insn)
+    else:
+        return
+
+    for vv in derefs(f.vw, v):
+        try:
+            s = read_string(f.vw, vv).rstrip("\x00")
+        except ValueError:
+            continue
+        else:
+            if len(s) >= 4:
+                yield String(s), ih.address
+
+
+def extract_operand_features(f: FunctionHandle, bb, insn: InsnHandle) -> Iterator[Tuple[Feature, Address]]:
+    for i, oper in enumerate(insn.inner.opers):
+        for op_handler in OPERAND_HANDLERS:
+            for feature, addr in op_handler(f, bb, insn, i, oper):
+                yield feature, addr
+
+
+OPERAND_HANDLERS: List[
+    Callable[[FunctionHandle, BBHandle, InsnHandle, int, envi.Operand], Iterator[Tuple[Feature, Address]]]
+] = [
+    extract_op_number_features,
+    extract_op_offset_features,
+    extract_op_string_features,
+]
+
+
+def extract_features(f, bb, insn) -> Iterator[Tuple[Feature, Address]]:
     """
     extract features from the given insn.
 
@@ -446,24 +731,23 @@ def extract_features(f, bb, insn):
       insn (vivisect...Instruction): the instruction to process.
 
     yields:
-      Feature, set[VA]: the features and their location found in this insn.
+      Tuple[Feature, Address]: the features and their location found in this insn.
     """
     for insn_handler in INSTRUCTION_HANDLERS:
-        for feature, va in insn_handler(f, bb, insn):
-            yield feature, va
+        for feature, addr in insn_handler(f, bb, insn):
+            yield feature, addr
 
 
-INSTRUCTION_HANDLERS = (
+INSTRUCTION_HANDLERS: List[Callable[[FunctionHandle, BBHandle, InsnHandle], Iterator[Tuple[Feature, Address]]]] = [
     extract_insn_api_features,
-    extract_insn_number_features,
-    extract_insn_string_features,
     extract_insn_bytes_features,
-    extract_insn_offset_features,
     extract_insn_nzxor_characteristic_features,
     extract_insn_mnemonic_features,
+    extract_insn_obfs_call_plus_5_characteristic_features,
     extract_insn_peb_access_characteristic_features,
     extract_insn_cross_section_cflow,
     extract_insn_segment_access_features,
     extract_function_calls_from,
     extract_function_indirect_call_characteristic_features,
-)
+    extract_operand_features,
+]

capa/features/file.py

@@ -1,21 +1,38 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
 
-from capa.features import Feature
+from capa.features.common import Feature
 
 
 class Export(Feature):
-    def __init__(self, value, description=None):
+    def __init__(self, value: str, description=None):
         # value is export name
-        super(Export, self).__init__(value, description)
+        super().__init__(value, description=description)
 
 
 class Import(Feature):
-    def __init__(self, value, description=None):
+    def __init__(self, value: str, description=None):
         # value is import name
-        super(Import, self).__init__(value, description)
+        super().__init__(value, description=description)
 
 
 class Section(Feature):
-    def __init__(self, value, description=None):
+    def __init__(self, value: str, description=None):
         # value is section name
-        super(Section, self).__init__(value, description)
+        super().__init__(value, description=description)
+
+
+class FunctionName(Feature):
+    """recognized name for statically linked function"""
+
+    def __init__(self, name: str, description=None):
+        # value is function name
+        super().__init__(name, description=description)
+        # override the name property set by `capa.features.Feature`
+        # that would be `functionname` (note missing dash)
+        self.name = "function-name"

capa/features/freeze.py

@@ -1,256 +0,0 @@
-"""
-capa freeze file format: `| capa0000 | + zlib(utf-8(json(...)))`
-
-json format:
-
-    {
-      'version': 1,
-      'functions': {
-        int(function va): {
-          'basic blocks': {
-            int(basic block va): {
-              'instructions': [instruction va, ...]
-            },
-            ...
-          },
-          ...
-        },
-        ...
-      },
-      'scopes': {
-        'file': [
-          (str(name), [any(arg), ...], int(va), ()),
-          ...
-        },
-        'function': [
-          (str(name), [any(arg), ...], int(va), (int(function va), )),
-          ...
-        ],
-        'basic block': [
-          (str(name), [any(arg), ...], int(va), (int(function va),
-                                                 int(basic block va))),
-          ...
-        ],
-        'instruction': [
-          (str(name), [any(arg), ...], int(va), (int(function va),
-                                                 int(basic block va),
-                                                 int(instruction va))),
-          ...
-        ],
-      }
-    }
-
-Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-"""
-import json
-import zlib
-import logging
-
-import capa.features
-import capa.features.file
-import capa.features.insn
-import capa.features.basicblock
-import capa.features.extractors
-from capa.helpers import hex
-
-logger = logging.getLogger(__name__)
-
-
-def serialize_feature(feature):
-    return feature.freeze_serialize()
-
-
-KNOWN_FEATURES = {F.__name__: F for F in capa.features.Feature.__subclasses__()}
-
-
-def deserialize_feature(doc):
-    F = KNOWN_FEATURES[doc[0]]
-    return F.freeze_deserialize(doc[1])
-
-
-def dumps(extractor):
-    """
-    serialize the given extractor to a string
-
-    args:
-      extractor: capa.features.extractor.FeatureExtractor:
-
-    returns:
-      str: the serialized features.
-    """
-    ret = {"version": 1, "functions": {}, "scopes": {"file": [], "function": [], "basic block": [], "instruction": [],}}
-
-    for feature, va in extractor.extract_file_features():
-        ret["scopes"]["file"].append(serialize_feature(feature) + (hex(va), ()))
-
-    for f in extractor.get_functions():
-        ret["functions"][hex(f)] = {}
-
-        for feature, va in extractor.extract_function_features(f):
-            ret["scopes"]["function"].append(serialize_feature(feature) + (hex(va), (hex(f),)))
-
-        for bb in extractor.get_basic_blocks(f):
-            ret["functions"][hex(f)][hex(bb)] = []
-
-            for feature, va in extractor.extract_basic_block_features(f, bb):
-                ret["scopes"]["basic block"].append(serialize_feature(feature) + (hex(va), (hex(f), hex(bb),)))
-
-            for insn, insnva in sorted([(insn, int(insn)) for insn in extractor.get_instructions(f, bb)]):
-                ret["functions"][hex(f)][hex(bb)].append(hex(insnva))
-
-                for feature, va in extractor.extract_insn_features(f, bb, insn):
-                    ret["scopes"]["instruction"].append(
-                        serialize_feature(feature) + (hex(va), (hex(f), hex(bb), hex(insnva),))
-                    )
-    return json.dumps(ret)
-
-
-def loads(s):
-    """deserialize a set of features (as a NullFeatureExtractor) from a string."""
-    doc = json.loads(s)
-
-    if doc.get("version") != 1:
-        raise ValueError("unsupported freeze format version: %d" % (doc.get("version")))
-
-    features = {
-        "file features": [],
-        "functions": {},
-    }
-
-    for fva, function in doc.get("functions", {}).items():
-        fva = int(fva, 0x10)
-        features["functions"][fva] = {
-            "features": [],
-            "basic blocks": {},
-        }
-
-        for bbva, bb in function.items():
-            bbva = int(bbva, 0x10)
-            features["functions"][fva]["basic blocks"][bbva] = {
-                "features": [],
-                "instructions": {},
-            }
-
-            for insnva in bb:
-                insnva = int(insnva, 0x10)
-                features["functions"][fva]["basic blocks"][bbva]["instructions"][insnva] = {
-                    "features": [],
-                }
-
-    # in the following blocks, each entry looks like:
-    #
-    #     ('MatchedRule', ('foo', ), '0x401000', ('0x401000', ))
-    #      ^^^^^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^^^  ^^^^^^^^^^^^^^
-    #      feature name   args       addr         func/bb/insn
-    for feature in doc.get("scopes", {}).get("file", []):
-        va, loc = feature[2:]
-        va = int(va, 0x10)
-        feature = deserialize_feature(feature[:2])
-        features["file features"].append((va, feature))
-
-    for feature in doc.get("scopes", {}).get("function", []):
-        # fetch the pair like:
-        #
-        #     ('0x401000', ('0x401000', ))
-        #      ^^^^^^^^^^  ^^^^^^^^^^^^^^
-        #      addr         func/bb/insn
-        va, loc = feature[2:]
-        va = int(va, 0x10)
-        loc = [int(lo, 0x10) for lo in loc]
-
-        # decode the feature from the pair like:
-        #
-        #     ('MatchedRule', ('foo', ))
-        #      ^^^^^^^^^^^^^  ^^^^^^^^^
-        #      feature name   args
-        feature = deserialize_feature(feature[:2])
-        features["functions"][loc[0]]["features"].append((va, feature))
-
-    for feature in doc.get("scopes", {}).get("basic block", []):
-        va, loc = feature[2:]
-        va = int(va, 0x10)
-        loc = [int(lo, 0x10) for lo in loc]
-        feature = deserialize_feature(feature[:2])
-        features["functions"][loc[0]]["basic blocks"][loc[1]]["features"].append((va, feature))
-
-    for feature in doc.get("scopes", {}).get("instruction", []):
-        va, loc = feature[2:]
-        va = int(va, 0x10)
-        loc = [int(lo, 0x10) for lo in loc]
-        feature = deserialize_feature(feature[:2])
-        features["functions"][loc[0]]["basic blocks"][loc[1]]["instructions"][loc[2]]["features"].append((va, feature))
-
-    return capa.features.extractors.NullFeatureExtractor(features)
-
-
-MAGIC = "capa0000".encode("ascii")
-
-
-def dump(extractor):
-    """serialize the given extractor to a byte array."""
-    return MAGIC + zlib.compress(dumps(extractor).encode("utf-8"))
-
-
-def is_freeze(buf):
-    return buf[: len(MAGIC)] == MAGIC
-
-
-def load(buf):
-    """deserialize a set of features (as a NullFeatureExtractor) from a byte array."""
-    if not is_freeze(buf):
-        raise ValueError("missing magic header")
-    return loads(zlib.decompress(buf[len(MAGIC) :]).decode("utf-8"))
-
-
-def main(argv=None):
-    import sys
-    import argparse
-    import capa.main
-
-    if argv is None:
-        argv = sys.argv[1:]
-
-    formats = [
-        ("auto", "(default) detect file type automatically"),
-        ("pe", "Windows PE file"),
-        ("sc32", "32-bit shellcode"),
-        ("sc64", "64-bit shellcode"),
-    ]
-    format_help = ", ".join(["%s: %s" % (f[0], f[1]) for f in formats])
-
-    parser = argparse.ArgumentParser(description="save capa features to a file")
-    parser.add_argument("sample", type=str, help="Path to sample to analyze")
-    parser.add_argument("output", type=str, help="Path to output file")
-    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
-    parser.add_argument("-q", "--quiet", action="store_true", help="Disable all output but errors")
-    parser.add_argument(
-        "-f", "--format", choices=[f[0] for f in formats], default="auto", help="Select sample format, %s" % format_help
-    )
-    args = parser.parse_args(args=argv)
-
-    if args.quiet:
-        logging.basicConfig(level=logging.ERROR)
-        logging.getLogger().setLevel(logging.ERROR)
-    elif args.verbose:
-        logging.basicConfig(level=logging.DEBUG)
-        logging.getLogger().setLevel(logging.DEBUG)
-    else:
-        logging.basicConfig(level=logging.INFO)
-        logging.getLogger().setLevel(logging.INFO)
-
-    vw = capa.main.get_workspace(args.sample, args.format)
-
-    # don't import this at top level to support ida/py3 backend
-    import capa.features.extractors.viv
-
-    extractor = capa.features.extractors.viv.VivisectFeatureExtractor(vw, args.sample)
-    with open(args.output, "wb") as f:
-        f.write(dump(extractor))
-
-    return 0
-
-
-if __name__ == "__main__":
-    import sys
-
-    sys.exit(main())

capa/features/freeze/__init__.py

@@ -0,0 +1,399 @@
+"""
+capa freeze file format: `| capa0000 | + zlib(utf-8(json(...)))`
+
+Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+You may obtain a copy of the License at: [package root]/LICENSE.txt
+Unless required by applicable law or agreed to in writing, software distributed under the License
+ is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License.
+"""
+import zlib
+import logging
+from enum import Enum
+from typing import List, Tuple, Union
+
+from pydantic import Field, BaseModel, ConfigDict
+
+import capa.helpers
+import capa.version
+import capa.features.file
+import capa.features.insn
+import capa.features.common
+import capa.features.address
+import capa.features.basicblock
+import capa.features.extractors.base_extractor
+from capa.helpers import assert_never
+from capa.features.freeze.features import Feature, feature_from_capa
+
+logger = logging.getLogger(__name__)
+
+
+class HashableModel(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+
+class AddressType(str, Enum):
+    ABSOLUTE = "absolute"
+    RELATIVE = "relative"
+    FILE = "file"
+    DN_TOKEN = "dn token"
+    DN_TOKEN_OFFSET = "dn token offset"
+    NO_ADDRESS = "no address"
+
+
+class Address(HashableModel):
+    type: AddressType
+    value: Union[int, Tuple[int, int], None] = None  # None default value to support deserialization of NO_ADDRESS
+
+    @classmethod
+    def from_capa(cls, a: capa.features.address.Address) -> "Address":
+        if isinstance(a, capa.features.address.AbsoluteVirtualAddress):
+            return cls(type=AddressType.ABSOLUTE, value=int(a))
+
+        elif isinstance(a, capa.features.address.RelativeVirtualAddress):
+            return cls(type=AddressType.RELATIVE, value=int(a))
+
+        elif isinstance(a, capa.features.address.FileOffsetAddress):
+            return cls(type=AddressType.FILE, value=int(a))
+
+        elif isinstance(a, capa.features.address.DNTokenAddress):
+            return cls(type=AddressType.DN_TOKEN, value=int(a))
+
+        elif isinstance(a, capa.features.address.DNTokenOffsetAddress):
+            return cls(type=AddressType.DN_TOKEN_OFFSET, value=(a.token, a.offset))
+
+        elif a == capa.features.address.NO_ADDRESS or isinstance(a, capa.features.address._NoAddress):
+            return cls(type=AddressType.NO_ADDRESS, value=None)
+
+        elif isinstance(a, capa.features.address.Address) and not issubclass(type(a), capa.features.address.Address):
+            raise ValueError("don't use an Address instance directly")
+
+        elif isinstance(a, capa.features.address.Address):
+            raise ValueError("don't use an Address instance directly")
+
+        else:
+            assert_never(a)
+
+    def to_capa(self) -> capa.features.address.Address:
+        if self.type is AddressType.ABSOLUTE:
+            assert isinstance(self.value, int)
+            return capa.features.address.AbsoluteVirtualAddress(self.value)
+
+        elif self.type is AddressType.RELATIVE:
+            assert isinstance(self.value, int)
+            return capa.features.address.RelativeVirtualAddress(self.value)
+
+        elif self.type is AddressType.FILE:
+            assert isinstance(self.value, int)
+            return capa.features.address.FileOffsetAddress(self.value)
+
+        elif self.type is AddressType.DN_TOKEN:
+            assert isinstance(self.value, int)
+            return capa.features.address.DNTokenAddress(self.value)
+
+        elif self.type is AddressType.DN_TOKEN_OFFSET:
+            assert isinstance(self.value, tuple)
+            token, offset = self.value
+            assert isinstance(token, int)
+            assert isinstance(offset, int)
+            return capa.features.address.DNTokenOffsetAddress(token, offset)
+
+        elif self.type is AddressType.NO_ADDRESS:
+            return capa.features.address.NO_ADDRESS
+
+        else:
+            assert_never(self.type)
+
+    def __lt__(self, other: "Address") -> bool:
+        if self.type != other.type:
+            return self.type < other.type
+
+        if self.type is AddressType.NO_ADDRESS:
+            return True
+
+        else:
+            assert self.type == other.type
+            # mypy doesn't realize we've proven that either
+            # both are ints, or both are tuples of ints.
+            # and both of these are comparable.
+            return self.value < other.value  # type: ignore
+
+
+class GlobalFeature(HashableModel):
+    feature: Feature
+
+
+class FileFeature(HashableModel):
+    address: Address
+    feature: Feature
+
+
+class FunctionFeature(HashableModel):
+    """
+    args:
+        function: the address of the function to which this feature belongs.
+        address: the address at which this feature is found.
+
+    function != address because, e.g., the feature may be found *within* the scope (function).
+    versus right at its starting address.
+    """
+
+    function: Address
+    address: Address
+    feature: Feature
+
+
+class BasicBlockFeature(HashableModel):
+    """
+    args:
+        basic_block: the address of the basic block to which this feature belongs.
+        address: the address at which this feature is found.
+
+    basic_block != address because, e.g., the feature may be found *within* the scope (basic block).
+    versus right at its starting address.
+    """
+
+    basic_block: Address = Field(alias="basic block")
+    address: Address
+    feature: Feature
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class InstructionFeature(HashableModel):
+    """
+    args:
+        instruction: the address of the instruction to which this feature belongs.
+        address: the address at which this feature is found.
+
+    instruction != address because, e.g., the feature may be found *within* the scope (basic block),
+    versus right at its starting address.
+    """
+
+    instruction: Address
+    address: Address
+    feature: Feature
+
+
+class InstructionFeatures(BaseModel):
+    address: Address
+    features: Tuple[InstructionFeature, ...]
+
+
+class BasicBlockFeatures(BaseModel):
+    address: Address
+    features: Tuple[BasicBlockFeature, ...]
+    instructions: Tuple[InstructionFeatures, ...]
+
+
+class FunctionFeatures(BaseModel):
+    address: Address
+    features: Tuple[FunctionFeature, ...]
+    basic_blocks: Tuple[BasicBlockFeatures, ...] = Field(alias="basic blocks")
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class Features(BaseModel):
+    global_: Tuple[GlobalFeature, ...] = Field(alias="global")
+    file: Tuple[FileFeature, ...]
+    functions: Tuple[FunctionFeatures, ...]
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class Extractor(BaseModel):
+    name: str
+    version: str = capa.version.__version__
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class Freeze(BaseModel):
+    version: int = 2
+    base_address: Address = Field(alias="base address")
+    extractor: Extractor
+    features: Features
+    model_config = ConfigDict(populate_by_name=True)
+
+
+def dumps(extractor: capa.features.extractors.base_extractor.FeatureExtractor) -> str:
+    """
+    serialize the given extractor to a string
+    """
+
+    global_features: List[GlobalFeature] = []
+    for feature, _ in extractor.extract_global_features():
+        global_features.append(
+            GlobalFeature(
+                feature=feature_from_capa(feature),
+            )
+        )
+
+    file_features: List[FileFeature] = []
+    for feature, address in extractor.extract_file_features():
+        file_features.append(
+            FileFeature(
+                feature=feature_from_capa(feature),
+                address=Address.from_capa(address),
+            )
+        )
+
+    function_features: List[FunctionFeatures] = []
+    for f in extractor.get_functions():
+        faddr = Address.from_capa(f.address)
+        ffeatures = [
+            FunctionFeature(
+                function=faddr,
+                address=Address.from_capa(addr),
+                feature=feature_from_capa(feature),
+            )
+            for feature, addr in extractor.extract_function_features(f)
+        ]
+
+        basic_blocks = []
+        for bb in extractor.get_basic_blocks(f):
+            bbaddr = Address.from_capa(bb.address)
+            bbfeatures = [
+                BasicBlockFeature(
+                    basic_block=bbaddr,
+                    address=Address.from_capa(addr),
+                    feature=feature_from_capa(feature),
+                )  # type: ignore
+                # Mypy is unable to recognise `basic_block` as a argument due to alias
+                for feature, addr in extractor.extract_basic_block_features(f, bb)
+            ]
+
+            instructions = []
+            for insn in extractor.get_instructions(f, bb):
+                iaddr = Address.from_capa(insn.address)
+                ifeatures = [
+                    InstructionFeature(
+                        instruction=iaddr,
+                        address=Address.from_capa(addr),
+                        feature=feature_from_capa(feature),
+                    )
+                    for feature, addr in extractor.extract_insn_features(f, bb, insn)
+                ]
+
+                instructions.append(
+                    InstructionFeatures(
+                        address=iaddr,
+                        features=tuple(ifeatures),
+                    )
+                )
+
+            basic_blocks.append(
+                BasicBlockFeatures(
+                    address=bbaddr,
+                    features=tuple(bbfeatures),
+                    instructions=tuple(instructions),
+                )
+            )
+
+        function_features.append(
+            FunctionFeatures(
+                address=faddr,
+                features=tuple(ffeatures),
+                basic_blocks=basic_blocks,
+            )  # type: ignore
+            # Mypy is unable to recognise `basic_blocks` as a argument due to alias
+        )
+
+    features = Features(
+        global_=global_features,
+        file=tuple(file_features),
+        functions=tuple(function_features),
+    )  # type: ignore
+    # Mypy is unable to recognise `global_` as a argument due to alias
+
+    freeze = Freeze(
+        version=2,
+        base_address=Address.from_capa(extractor.get_base_address()),
+        extractor=Extractor(name=extractor.__class__.__name__),
+        features=features,
+    )  # type: ignore
+    # Mypy is unable to recognise `base_address` as a argument due to alias
+
+    return freeze.model_dump_json()
+
+
+def loads(s: str) -> capa.features.extractors.base_extractor.FeatureExtractor:
+    """deserialize a set of features (as a NullFeatureExtractor) from a string."""
+    import capa.features.extractors.null as null
+
+    freeze = Freeze.model_validate_json(s)
+    if freeze.version != 2:
+        raise ValueError(f"unsupported freeze format version: {freeze.version}")
+
+    return null.NullFeatureExtractor(
+        base_address=freeze.base_address.to_capa(),
+        global_features=[f.feature.to_capa() for f in freeze.features.global_],
+        file_features=[(f.address.to_capa(), f.feature.to_capa()) for f in freeze.features.file],
+        functions={
+            f.address.to_capa(): null.FunctionFeatures(
+                features=[(fe.address.to_capa(), fe.feature.to_capa()) for fe in f.features],
+                basic_blocks={
+                    bb.address.to_capa(): null.BasicBlockFeatures(
+                        features=[(fe.address.to_capa(), fe.feature.to_capa()) for fe in bb.features],
+                        instructions={
+                            i.address.to_capa(): null.InstructionFeatures(
+                                features=[(fe.address.to_capa(), fe.feature.to_capa()) for fe in i.features]
+                            )
+                            for i in bb.instructions
+                        },
+                    )
+                    for bb in f.basic_blocks
+                },
+            )
+            for f in freeze.features.functions
+        },
+    )
+
+
+MAGIC = "capa0000".encode("ascii")
+
+
+def dump(extractor: capa.features.extractors.base_extractor.FeatureExtractor) -> bytes:
+    """serialize the given extractor to a byte array."""
+    return MAGIC + zlib.compress(dumps(extractor).encode("utf-8"))
+
+
+def is_freeze(buf: bytes) -> bool:
+    return buf[: len(MAGIC)] == MAGIC
+
+
+def load(buf: bytes) -> capa.features.extractors.base_extractor.FeatureExtractor:
+    """deserialize a set of features (as a NullFeatureExtractor) from a byte array."""
+    if not is_freeze(buf):
+        raise ValueError("missing magic header")
+    return loads(zlib.decompress(buf[len(MAGIC) :]).decode("utf-8"))
+
+
+def main(argv=None):
+    import sys
+    import argparse
+    from pathlib import Path
+
+    import capa.main
+
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(description="save capa features to a file")
+    capa.main.install_common_args(parser, {"sample", "format", "backend", "os", "signatures"})
+    parser.add_argument("output", type=str, help="Path to output file")
+    args = parser.parse_args(args=argv)
+    capa.main.handle_common_args(args)
+
+    sigpaths = capa.main.get_signatures(args.signatures)
+
+    extractor = capa.main.get_extractor(args.sample, args.format, args.os, args.backend, sigpaths, False)
+
+    Path(args.output).write_bytes(dump(extractor))
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

capa/features/freeze/features.py

@@ -0,0 +1,376 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import binascii
+from typing import Union, Optional
+
+from pydantic import Field, BaseModel, ConfigDict
+
+import capa.features.file
+import capa.features.insn
+import capa.features.common
+import capa.features.basicblock
+
+
+class FeatureModel(BaseModel):
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    def to_capa(self) -> capa.features.common.Feature:
+        if isinstance(self, OSFeature):
+            return capa.features.common.OS(self.os, description=self.description)
+
+        elif isinstance(self, ArchFeature):
+            return capa.features.common.Arch(self.arch, description=self.description)
+
+        elif isinstance(self, FormatFeature):
+            return capa.features.common.Format(self.format, description=self.description)
+
+        elif isinstance(self, MatchFeature):
+            return capa.features.common.MatchedRule(self.match, description=self.description)
+
+        elif isinstance(
+            self,
+            CharacteristicFeature,
+        ):
+            return capa.features.common.Characteristic(self.characteristic, description=self.description)
+
+        elif isinstance(self, ExportFeature):
+            return capa.features.file.Export(self.export, description=self.description)
+
+        elif isinstance(self, ImportFeature):
+            return capa.features.file.Import(self.import_, description=self.description)
+
+        elif isinstance(self, SectionFeature):
+            return capa.features.file.Section(self.section, description=self.description)
+
+        elif isinstance(self, FunctionNameFeature):
+            return capa.features.file.FunctionName(self.function_name, description=self.description)
+
+        elif isinstance(self, SubstringFeature):
+            return capa.features.common.Substring(self.substring, description=self.description)
+
+        elif isinstance(self, RegexFeature):
+            return capa.features.common.Regex(self.regex, description=self.description)
+
+        elif isinstance(self, StringFeature):
+            return capa.features.common.String(self.string, description=self.description)
+
+        elif isinstance(self, ClassFeature):
+            return capa.features.common.Class(self.class_, description=self.description)
+
+        elif isinstance(self, NamespaceFeature):
+            return capa.features.common.Namespace(self.namespace, description=self.description)
+
+        elif isinstance(self, BasicBlockFeature):
+            return capa.features.basicblock.BasicBlock(description=self.description)
+
+        elif isinstance(self, APIFeature):
+            return capa.features.insn.API(self.api, description=self.description)
+
+        elif isinstance(self, PropertyFeature):
+            return capa.features.insn.Property(self.property, access=self.access, description=self.description)
+
+        elif isinstance(self, NumberFeature):
+            return capa.features.insn.Number(self.number, description=self.description)
+
+        elif isinstance(self, BytesFeature):
+            return capa.features.common.Bytes(binascii.unhexlify(self.bytes), description=self.description)
+
+        elif isinstance(self, OffsetFeature):
+            return capa.features.insn.Offset(self.offset, description=self.description)
+
+        elif isinstance(self, MnemonicFeature):
+            return capa.features.insn.Mnemonic(self.mnemonic, description=self.description)
+
+        elif isinstance(self, OperandNumberFeature):
+            return capa.features.insn.OperandNumber(
+                self.index,
+                self.operand_number,
+                description=self.description,
+            )
+
+        elif isinstance(self, OperandOffsetFeature):
+            return capa.features.insn.OperandOffset(
+                self.index,
+                self.operand_offset,
+                description=self.description,
+            )
+
+        else:
+            raise NotImplementedError(f"Feature.to_capa({type(self)}) not implemented")
+
+
+def feature_from_capa(f: capa.features.common.Feature) -> "Feature":
+    if isinstance(f, capa.features.common.OS):
+        assert isinstance(f.value, str)
+        return OSFeature(os=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.Arch):
+        assert isinstance(f.value, str)
+        return ArchFeature(arch=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.Format):
+        assert isinstance(f.value, str)
+        return FormatFeature(format=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.MatchedRule):
+        assert isinstance(f.value, str)
+        return MatchFeature(match=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.Characteristic):
+        assert isinstance(f.value, str)
+        return CharacteristicFeature(characteristic=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.file.Export):
+        assert isinstance(f.value, str)
+        return ExportFeature(export=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.file.Import):
+        assert isinstance(f.value, str)
+        return ImportFeature(import_=f.value, description=f.description)  # type: ignore
+        # Mypy is unable to recognise `import_` as a argument due to alias
+
+    elif isinstance(f, capa.features.file.Section):
+        assert isinstance(f.value, str)
+        return SectionFeature(section=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.file.FunctionName):
+        assert isinstance(f.value, str)
+        return FunctionNameFeature(function_name=f.value, description=f.description)  # type: ignore
+        # Mypy is unable to recognise `function_name` as a argument due to alias
+
+    # must come before check for String due to inheritance
+    elif isinstance(f, capa.features.common.Substring):
+        assert isinstance(f.value, str)
+        return SubstringFeature(substring=f.value, description=f.description)
+
+    # must come before check for String due to inheritance
+    elif isinstance(f, capa.features.common.Regex):
+        assert isinstance(f.value, str)
+        return RegexFeature(regex=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.String):
+        assert isinstance(f.value, str)
+        return StringFeature(string=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.Class):
+        assert isinstance(f.value, str)
+        return ClassFeature(class_=f.value, description=f.description)  # type: ignore
+        # Mypy is unable to recognise `class_` as a argument due to alias
+
+    elif isinstance(f, capa.features.common.Namespace):
+        assert isinstance(f.value, str)
+        return NamespaceFeature(namespace=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.basicblock.BasicBlock):
+        return BasicBlockFeature(description=f.description)
+
+    elif isinstance(f, capa.features.insn.API):
+        assert isinstance(f.value, str)
+        return APIFeature(api=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.insn.Property):
+        assert isinstance(f.value, str)
+        return PropertyFeature(property=f.value, access=f.access, description=f.description)
+
+    elif isinstance(f, capa.features.insn.Number):
+        assert isinstance(f.value, (int, float))
+        return NumberFeature(number=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.common.Bytes):
+        buf = f.value
+        assert isinstance(buf, bytes)
+        return BytesFeature(bytes=binascii.hexlify(buf).decode("ascii"), description=f.description)
+
+    elif isinstance(f, capa.features.insn.Offset):
+        assert isinstance(f.value, int)
+        return OffsetFeature(offset=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.insn.Mnemonic):
+        assert isinstance(f.value, str)
+        return MnemonicFeature(mnemonic=f.value, description=f.description)
+
+    elif isinstance(f, capa.features.insn.OperandNumber):
+        assert isinstance(f.value, int)
+        return OperandNumberFeature(index=f.index, operand_number=f.value, description=f.description)  # type: ignore
+        # Mypy is unable to recognise `operand_number` as a argument due to alias
+
+    elif isinstance(f, capa.features.insn.OperandOffset):
+        assert isinstance(f.value, int)
+        return OperandOffsetFeature(index=f.index, operand_offset=f.value, description=f.description)  # type: ignore
+        # Mypy is unable to recognise `operand_offset` as a argument due to alias
+
+    else:
+        raise NotImplementedError(f"feature_from_capa({type(f)}) not implemented")
+
+
+class OSFeature(FeatureModel):
+    type: str = "os"
+    os: str
+    description: Optional[str] = None
+
+
+class ArchFeature(FeatureModel):
+    type: str = "arch"
+    arch: str
+    description: Optional[str] = None
+
+
+class FormatFeature(FeatureModel):
+    type: str = "format"
+    format: str
+    description: Optional[str] = None
+
+
+class MatchFeature(FeatureModel):
+    type: str = "match"
+    match: str
+    description: Optional[str] = None
+
+
+class CharacteristicFeature(FeatureModel):
+    type: str = "characteristic"
+    characteristic: str
+    description: Optional[str] = None
+
+
+class ExportFeature(FeatureModel):
+    type: str = "export"
+    export: str
+    description: Optional[str] = None
+
+
+class ImportFeature(FeatureModel):
+    type: str = "import"
+    import_: str = Field(alias="import")
+    description: Optional[str] = None
+
+
+class SectionFeature(FeatureModel):
+    type: str = "section"
+    section: str
+    description: Optional[str] = None
+
+
+class FunctionNameFeature(FeatureModel):
+    type: str = "function name"
+    function_name: str = Field(alias="function name")
+    description: Optional[str] = None
+
+
+class SubstringFeature(FeatureModel):
+    type: str = "substring"
+    substring: str
+    description: Optional[str] = None
+
+
+class RegexFeature(FeatureModel):
+    type: str = "regex"
+    regex: str
+    description: Optional[str] = None
+
+
+class StringFeature(FeatureModel):
+    type: str = "string"
+    string: str
+    description: Optional[str] = None
+
+
+class ClassFeature(FeatureModel):
+    type: str = "class"
+    class_: str = Field(alias="class")
+    description: Optional[str] = None
+
+
+class NamespaceFeature(FeatureModel):
+    type: str = "namespace"
+    namespace: str
+    description: Optional[str] = None
+
+
+class BasicBlockFeature(FeatureModel):
+    type: str = "basic block"
+    description: Optional[str] = None
+
+
+class APIFeature(FeatureModel):
+    type: str = "api"
+    api: str
+    description: Optional[str] = None
+
+
+class PropertyFeature(FeatureModel):
+    type: str = "property"
+    access: Optional[str] = None
+    property: str
+    description: Optional[str] = None
+
+
+class NumberFeature(FeatureModel):
+    type: str = "number"
+    number: Union[int, float]
+    description: Optional[str] = None
+
+
+class BytesFeature(FeatureModel):
+    type: str = "bytes"
+    bytes: str
+    description: Optional[str] = None
+
+
+class OffsetFeature(FeatureModel):
+    type: str = "offset"
+    offset: int
+    description: Optional[str] = None
+
+
+class MnemonicFeature(FeatureModel):
+    type: str = "mnemonic"
+    mnemonic: str
+    description: Optional[str] = None
+
+
+class OperandNumberFeature(FeatureModel):
+    type: str = "operand number"
+    index: int
+    operand_number: int = Field(alias="operand number")
+    description: Optional[str] = None
+
+
+class OperandOffsetFeature(FeatureModel):
+    type: str = "operand offset"
+    index: int
+    operand_offset: int = Field(alias="operand offset")
+    description: Optional[str] = None
+
+
+Feature = Union[
+    OSFeature,
+    ArchFeature,
+    FormatFeature,
+    MatchFeature,
+    CharacteristicFeature,
+    ExportFeature,
+    ImportFeature,
+    SectionFeature,
+    FunctionNameFeature,
+    SubstringFeature,
+    RegexFeature,
+    StringFeature,
+    ClassFeature,
+    NamespaceFeature,
+    APIFeature,
+    PropertyFeature,
+    NumberFeature,
+    BytesFeature,
+    OffsetFeature,
+    MnemonicFeature,
+    OperandNumberFeature,
+    OperandOffsetFeature,
+    # Note! this must be last, see #1161
+    BasicBlockFeature,
+]

capa/features/insn.py

@@ -1,34 +1,169 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import abc
+from typing import Union, Optional
 
-from capa.features import Feature
+import capa.helpers
+from capa.features.common import VALID_FEATURE_ACCESS, Feature
+
+
+def hex(n: int) -> str:
+    """render the given number using upper case hex, like: 0x123ABC"""
+    if n < 0:
+        return f"-0x{(-n):X}"
+    else:
+        return f"0x{(n):X}"
 
 
 class API(Feature):
-    def __init__(self, name, description=None):
-        # Downcase library name if given
-        if "." in name:
-            modname, impname = name.split(".")
-            name = modname.lower() + "." + impname
+    def __init__(self, name: str, description=None):
+        super().__init__(name, description=description)
 
-        super(API, self).__init__(name, description)
+
+class _AccessFeature(Feature, abc.ABC):
+    # superclass: don't use directly
+    def __init__(self, value: str, access: Optional[str] = None, description: Optional[str] = None):
+        super().__init__(value, description=description)
+        if access is not None:
+            if access not in VALID_FEATURE_ACCESS:
+                raise ValueError(f"{self.name} access type {access} not valid")
+        self.access = access
+
+    def __hash__(self):
+        return hash((self.name, self.value, self.access))
+
+    def __eq__(self, other):
+        return super().__eq__(other) and self.access == other.access
+
+    def get_name_str(self) -> str:
+        if self.access is not None:
+            return f"{self.name}/{self.access}"
+        return self.name
+
+
+class Property(_AccessFeature):
+    def __init__(self, value: str, access: Optional[str] = None, description=None):
+        super().__init__(value, access=access, description=description)
 
 
 class Number(Feature):
-    def __init__(self, value, description=None):
-        super(Number, self).__init__(value, description)
+    def __init__(self, value: Union[int, float], description=None):
+        """
+        args:
+          value (int or float): positive or negative integer, or floating point number.
+
+        the range of the value is:
+          - if positive, the range of u64
+          - if negative, the range of i64
+          - if floating, the range and precision of double
+        """
+        super().__init__(value, description=description)
 
     def get_value_str(self):
-        return "0x%X" % self.value
+        if isinstance(self.value, int):
+            return capa.helpers.hex(self.value)
+        elif isinstance(self.value, float):
+            return str(self.value)
+        else:
+            raise ValueError(f"invalid value type {type(self.value)}")
+
+
+# max recognized structure size (and therefore, offset size)
+MAX_STRUCTURE_SIZE = 0x10000
 
 
 class Offset(Feature):
-    def __init__(self, value, description=None):
-        super(Offset, self).__init__(value, description)
+    def __init__(self, value: int, description=None):
+        """
+        args:
+          value (int): the offset, which can be positive or negative.
+
+        the range of the value is:
+          - if positive, the range of u64
+          - if negative, the range of i64
+        """
+        super().__init__(value, description=description)
 
     def get_value_str(self):
-        return "0x%X" % self.value
+        assert isinstance(self.value, int)
+        return hex(self.value)
 
 
 class Mnemonic(Feature):
-    def __init__(self, value, description=None):
-        super(Mnemonic, self).__init__(value, description)
+    def __init__(self, value: str, description=None):
+        super().__init__(value, description=description)
+
+
+# max number of operands to consider for a given instruction.
+# since we only support Intel and .NET, we can assume this is 3
+# which covers cases up to e.g. "vinserti128 ymm0,ymm0,ymm5,1"
+MAX_OPERAND_COUNT = 4
+MAX_OPERAND_INDEX = MAX_OPERAND_COUNT - 1
+
+
+class _Operand(Feature, abc.ABC):
+    # superclass: don't use directly
+    # subclasses should set self.name and provide the value string formatter
+    def __init__(self, index: int, value: Union[int, float], description=None):
+        super().__init__(value, description=description)
+        self.index = index
+
+    def __hash__(self):
+        return hash((self.name, self.value))
+
+    def __eq__(self, other):
+        return super().__eq__(other) and self.index == other.index
+
+
+class OperandNumber(_Operand):
+    # cached names so we don't do extra string formatting every ctor
+    NAMES = [f"operand[{i}].number" for i in range(MAX_OPERAND_COUNT)]
+
+    # operand[i].number: 0x12
+    def __init__(self, index: int, value: Union[int, float], description=None):
+        """
+        args:
+          value (int or float): positive or negative integer, or floating point number.
+
+        the range of the value is:
+          - if positive, the range of u64
+          - if negative, the range of i64
+          - if floating, the range and precision of double
+        """
+        super().__init__(index, value, description=description)
+        self.name = self.NAMES[index]
+
+    def get_value_str(self) -> str:
+        if isinstance(self.value, int):
+            return capa.helpers.hex(self.value)
+        elif isinstance(self.value, float):
+            return str(self.value)
+        else:
+            raise ValueError("invalid value type")
+
+
+class OperandOffset(_Operand):
+    # cached names so we don't do extra string formatting every ctor
+    NAMES = [f"operand[{i}].offset" for i in range(MAX_OPERAND_COUNT)]
+
+    # operand[i].offset: 0x12
+    def __init__(self, index: int, value: int, description=None):
+        """
+        args:
+          value (int): the offset, which can be positive or negative.
+
+        the range of the value is:
+          - if positive, the range of u64
+          - if negative, the range of i64
+        """
+        super().__init__(index, value, description=description)
+        self.name = self.NAMES[index]
+
+    def get_value_str(self) -> str:
+        assert isinstance(self.value, int)
+        return hex(self.value)

capa/helpers.py

@@ -1,30 +1,159 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import inspect
+import logging
+import contextlib
+import importlib.util
+from typing import NoReturn
+from pathlib import Path
 
-import os
+import tqdm
 
-_hex = hex
+from capa.exceptions import UnsupportedFormatError
+from capa.features.common import FORMAT_PE, FORMAT_SC32, FORMAT_SC64, FORMAT_DOTNET, FORMAT_UNKNOWN, Format
+
+EXTENSIONS_SHELLCODE_32 = ("sc32", "raw32")
+EXTENSIONS_SHELLCODE_64 = ("sc64", "raw64")
+EXTENSIONS_ELF = "elf_"
+
+logger = logging.getLogger("capa")
 
 
-def hex(i):
-    # under py2.7, long integers get formatted with a trailing `L`
-    # and this is not pretty. so strip it out.
-    return _hex(oint(i)).rstrip("L")
+def hex(n: int) -> str:
+    """render the given number using upper case hex, like: 0x123ABC"""
+    if n < 0:
+        return f"-0x{(-n):X}"
+    else:
+        return f"0x{(n):X}"
 
 
-def oint(i):
-    # there seems to be some trouble with using `int(viv_utils.Function)`
-    # with the black magic we do with binding the `__int__()` routine.
-    # i haven't had a chance to debug this yet (and i have no hotel wifi).
-    # so in the meantime, detect this, and call the method directly.
-    try:
-        return int(i)
-    except TypeError:
-        return i.__int__()
-
-
-def get_file_taste(sample_path):
-    if not os.path.exists(sample_path):
-        raise IOError("sample path %s does not exist or cannot be accessed" % sample_path)
-    with open(sample_path, "rb") as f:
-        taste = f.read(8)
+def get_file_taste(sample_path: Path) -> bytes:
+    if not sample_path.exists():
+        raise IOError(f"sample path {sample_path} does not exist or cannot be accessed")
+    taste = sample_path.open("rb").read(8)
     return taste
+
+
+def is_runtime_ida():
+    return importlib.util.find_spec("idc") is not None
+
+
+def assert_never(value) -> NoReturn:
+    # careful: python -O will remove this assertion.
+    # but this is only used for type checking, so it's ok.
+    assert False, f"Unhandled value: {value} ({type(value).__name__})"  # noqa: B011
+
+
+def get_format_from_extension(sample: Path) -> str:
+    if sample.name.endswith(EXTENSIONS_SHELLCODE_32):
+        return FORMAT_SC32
+    elif sample.name.endswith(EXTENSIONS_SHELLCODE_64):
+        return FORMAT_SC64
+    return FORMAT_UNKNOWN
+
+
+def get_auto_format(path: Path) -> str:
+    format_ = get_format(path)
+    if format_ == FORMAT_UNKNOWN:
+        format_ = get_format_from_extension(path)
+    if format_ == FORMAT_UNKNOWN:
+        raise UnsupportedFormatError()
+    return format_
+
+
+def get_format(sample: Path) -> str:
+    # imported locally to avoid import cycle
+    from capa.features.extractors.common import extract_format
+    from capa.features.extractors.dnfile_ import DnfileFeatureExtractor
+
+    buf = sample.read_bytes()
+
+    for feature, _ in extract_format(buf):
+        if feature == Format(FORMAT_PE):
+            dnfile_extractor = DnfileFeatureExtractor(sample)
+            if dnfile_extractor.is_dotnet_file():
+                feature = Format(FORMAT_DOTNET)
+
+        assert isinstance(feature.value, str)
+        return feature.value
+
+    return FORMAT_UNKNOWN
+
+
+@contextlib.contextmanager
+def redirecting_print_to_tqdm(disable_progress):
+    """
+    tqdm (progress bar) expects to have fairly tight control over console output.
+    so calls to `print()` will break the progress bar and make things look bad.
+    so, this context manager temporarily replaces the `print` implementation
+    with one that is compatible with tqdm.
+    via: https://stackoverflow.com/a/42424890/87207
+    """
+    old_print = print  # noqa: T202 [reserved word print used]
+
+    def new_print(*args, **kwargs):
+        # If tqdm.tqdm.write raises error, use builtin print
+        if disable_progress:
+            old_print(*args, **kwargs)
+        else:
+            try:
+                tqdm.tqdm.write(*args, **kwargs)
+            except Exception:
+                old_print(*args, **kwargs)
+
+    try:
+        # Globally replace print with new_print.
+        # Verified this works manually on Python 3.11:
+        #     >>> import inspect
+        #     >>> inspect.builtins
+        #     <module 'builtins' (built-in)>
+        inspect.builtins.print = new_print  # type: ignore
+        yield
+    finally:
+        inspect.builtins.print = old_print  # type: ignore
+
+
+def log_unsupported_format_error():
+    logger.error("-" * 80)
+    logger.error(" Input file does not appear to be a PE or ELF file.")
+    logger.error(" ")
+    logger.error(
+        " capa currently only supports analyzing PE and ELF files (or shellcode, when using --format sc32|sc64)."
+    )
+    logger.error(" If you don't know the input file type, you can try using the `file` utility to guess it.")
+    logger.error("-" * 80)
+
+
+def log_unsupported_os_error():
+    logger.error("-" * 80)
+    logger.error(" Input file does not appear to target a supported OS.")
+    logger.error(" ")
+    logger.error(
+        " capa currently only supports analyzing executables for some operating systems (including Windows and Linux)."
+    )
+    logger.error("-" * 80)
+
+
+def log_unsupported_arch_error():
+    logger.error("-" * 80)
+    logger.error(" Input file does not appear to target a supported architecture.")
+    logger.error(" ")
+    logger.error(" capa currently only supports analyzing x86 (32- and 64-bit).")
+    logger.error("-" * 80)
+
+
+def log_unsupported_runtime_error():
+    logger.error("-" * 80)
+    logger.error(" Unsupported runtime or Python interpreter.")
+    logger.error(" ")
+    logger.error(" capa supports running under Python 3.8 and higher.")
+    logger.error(" ")
+    logger.error(
+        " If you're seeing this message on the command line, please ensure you're running a supported Python version."
+    )
+    logger.error("-" * 80)

capa/ida/explorer/item.py

@@ -1,268 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import sys
-import codecs
-
-import idc
-import idaapi
-from PyQt5 import QtCore
-
-import capa.ida.helpers
-
-
-def info_to_name(display):
-    """ extract root value from display name
-
-        e.g. function(my_function) => my_function
-    """
-    try:
-        return display.split("(")[1].rstrip(")")
-    except IndexError:
-        return ""
-
-
-def location_to_hex(location):
-    """ convert location to hex for display """
-    return "%08X" % location
-
-
-class CapaExplorerDataItem(object):
-    """ store data for CapaExplorerDataModel """
-
-    def __init__(self, parent, data):
-        """ """
-        self.pred = parent
-        self._data = data
-        self.children = []
-        self._checked = False
-
-        self.flags = (
-            QtCore.Qt.ItemIsEnabled
-            | QtCore.Qt.ItemIsSelectable
-            | QtCore.Qt.ItemIsTristate
-            | QtCore.Qt.ItemIsUserCheckable
-        )
-
-        if self.pred:
-            self.pred.appendChild(self)
-
-    def setIsEditable(self, isEditable=False):
-        """ modify item flags to be editable or not """
-        if isEditable:
-            self.flags |= QtCore.Qt.ItemIsEditable
-        else:
-            self.flags &= ~QtCore.Qt.ItemIsEditable
-
-    def setChecked(self, checked):
-        """ set item as checked """
-        self._checked = checked
-
-    def isChecked(self):
-        """ get item is checked """
-        return self._checked
-
-    def appendChild(self, item):
-        """ add child item
-
-            @param item: CapaExplorerDataItem*
-        """
-        self.children.append(item)
-
-    def child(self, row):
-        """ get child row
-
-            @param row: TODO
-        """
-        return self.children[row]
-
-    def childCount(self):
-        """ get child count """
-        return len(self.children)
-
-    def columnCount(self):
-        """ get column count """
-        return len(self._data)
-
-    def data(self, column):
-        """ get data at column """
-        try:
-            return self._data[column]
-        except IndexError:
-            return None
-
-    def parent(self):
-        """ get parent """
-        return self.pred
-
-    def row(self):
-        """ get row location """
-        if self.pred:
-            return self.pred.children.index(self)
-        return 0
-
-    def setData(self, column, value):
-        """ set data in column """
-        self._data[column] = value
-
-    def children(self):
-        """ yield children """
-        for child in self.children:
-            yield child
-
-    def removeChildren(self):
-        """ remove children from node """
-        del self.children[:]
-
-    def __str__(self):
-        """ get string representation of columns """
-        return " ".join([data for data in self._data if data])
-
-    @property
-    def info(self):
-        """ return data stored in information column """
-        return self._data[0]
-
-    @property
-    def location(self):
-        """ return data stored in location column """
-        try:
-            return int(self._data[1], 16)
-        except ValueError:
-            return None
-
-    @property
-    def details(self):
-        """ return data stored in details column """
-        return self._data[2]
-
-
-class CapaExplorerRuleItem(CapaExplorerDataItem):
-    """ store data relevant to capa function result """
-
-    fmt = "%s (%d matches)"
-
-    def __init__(self, parent, display, count, source):
-        """ """
-        display = self.fmt % (display, count) if count > 1 else display
-        super(CapaExplorerRuleItem, self).__init__(parent, [display, "", ""])
-        self._source = source
-
-    @property
-    def source(self):
-        """ return rule contents for display """
-        return self._source
-
-
-class CapaExplorerRuleMatchItem(CapaExplorerDataItem):
-    """ store data relevant to capa function match result """
-
-    def __init__(self, parent, display, source=""):
-        """ """
-        super(CapaExplorerRuleMatchItem, self).__init__(parent, [display, "", ""])
-        self._source = source
-
-    @property
-    def source(self):
-        """ return rule contents for display """
-        return self._source
-
-
-class CapaExplorerFunctionItem(CapaExplorerDataItem):
-    """ store data relevant to capa function result """
-
-    fmt = "function(%s)"
-
-    def __init__(self, parent, location):
-        """ """
-        super(CapaExplorerFunctionItem, self).__init__(
-            parent, [self.fmt % idaapi.get_name(location), location_to_hex(location), ""]
-        )
-
-    @property
-    def info(self):
-        """ """
-        info = super(CapaExplorerFunctionItem, self).info
-        display = info_to_name(info)
-        return display if display else info
-
-    @info.setter
-    def info(self, display):
-        """ """
-        self._data[0] = self.fmt % display
-
-
-class CapaExplorerSubscopeItem(CapaExplorerDataItem):
-    """ store data relevant to subscope """
-
-    fmt = "subscope(%s)"
-
-    def __init__(self, parent, scope):
-        """ """
-        super(CapaExplorerSubscopeItem, self).__init__(parent, [self.fmt % scope, "", ""])
-
-
-class CapaExplorerBlockItem(CapaExplorerDataItem):
-    """ store data relevant to capa basic block result """
-
-    fmt = "basic block(loc_%08X)"
-
-    def __init__(self, parent, location):
-        """ """
-        super(CapaExplorerBlockItem, self).__init__(parent, [self.fmt % location, location_to_hex(location), ""])
-
-
-class CapaExplorerDefaultItem(CapaExplorerDataItem):
-    """ store data relevant to capa default result """
-
-    def __init__(self, parent, display, details="", location=None):
-        """ """
-        location = location_to_hex(location) if location else ""
-        super(CapaExplorerDefaultItem, self).__init__(parent, [display, location, details])
-
-
-class CapaExplorerFeatureItem(CapaExplorerDataItem):
-    """ store data relevant to capa feature result """
-
-    def __init__(self, parent, display, location="", details=""):
-        """ """
-        location = location_to_hex(location) if location else ""
-        super(CapaExplorerFeatureItem, self).__init__(parent, [display, location, details])
-
-
-class CapaExplorerInstructionViewItem(CapaExplorerFeatureItem):
-    """ store data relevant to an instruction preview """
-
-    def __init__(self, parent, display, location):
-        """ """
-        details = capa.ida.helpers.get_disasm_line(location)
-        super(CapaExplorerInstructionViewItem, self).__init__(parent, display, location=location, details=details)
-        self.ida_highlight = idc.get_color(location, idc.CIC_ITEM)
-
-
-class CapaExplorerByteViewItem(CapaExplorerFeatureItem):
-    """ store data relevant to byte preview """
-
-    def __init__(self, parent, display, location):
-        """ """
-        byte_snap = idaapi.get_bytes(location, 32)
-
-        if byte_snap:
-            byte_snap = codecs.encode(byte_snap, "hex").upper()
-            if sys.version_info >= (3, 0):
-                details = " ".join([byte_snap[i : i + 2].decode() for i in range(0, len(byte_snap), 2)])
-            else:
-                details = " ".join([byte_snap[i : i + 2] for i in range(0, len(byte_snap), 2)])
-        else:
-            details = ""
-
-        super(CapaExplorerByteViewItem, self).__init__(parent, display, location=location, details=details)
-        self.ida_highlight = idc.get_color(location, idc.CIC_ITEM)
-
-
-class CapaExplorerStringViewItem(CapaExplorerFeatureItem):
-    """ store data relevant to string preview """
-
-    def __init__(self, parent, display, location):
-        """ """
-        super(CapaExplorerStringViewItem, self).__init__(parent, display, location=location)
-        self.ida_highlight = idc.get_color(location, idc.CIC_ITEM)

capa/ida/explorer/model.py

@@ -1,582 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-from collections import deque
-
-import idc
-import six
-import idaapi
-from PyQt5 import Qt, QtGui, QtCore
-
-import capa.ida.helpers
-import capa.render.utils as rutils
-from capa.ida.explorer.item import (
-    CapaExplorerDataItem,
-    CapaExplorerRuleItem,
-    CapaExplorerBlockItem,
-    CapaExplorerDefaultItem,
-    CapaExplorerFeatureItem,
-    CapaExplorerByteViewItem,
-    CapaExplorerFunctionItem,
-    CapaExplorerSubscopeItem,
-    CapaExplorerRuleMatchItem,
-    CapaExplorerStringViewItem,
-    CapaExplorerInstructionViewItem,
-)
-
-# default highlight color used in IDA window
-DEFAULT_HIGHLIGHT = 0xD096FF
-
-
-class CapaExplorerDataModel(QtCore.QAbstractItemModel):
-    """ """
-
-    COLUMN_INDEX_RULE_INFORMATION = 0
-    COLUMN_INDEX_VIRTUAL_ADDRESS = 1
-    COLUMN_INDEX_DETAILS = 2
-
-    COLUMN_COUNT = 3
-
-    def __init__(self, parent=None):
-        """ """
-        super(CapaExplorerDataModel, self).__init__(parent)
-        self.root_node = CapaExplorerDataItem(None, ["Rule Information", "Address", "Details"])
-
-    def reset(self):
-        """ """
-        # reset checkboxes and color highlights
-        # TODO: make less hacky
-        for idx in range(self.root_node.childCount()):
-            root_index = self.index(idx, 0, QtCore.QModelIndex())
-            for model_index in self.iterateChildrenIndexFromRootIndex(root_index, ignore_root=False):
-                model_index.internalPointer().setChecked(False)
-                self.reset_ida_highlighting(model_index.internalPointer(), False)
-                self.dataChanged.emit(model_index, model_index)
-
-    def clear(self):
-        """ """
-        self.beginResetModel()
-        self.root_node.removeChildren()
-        self.endResetModel()
-
-    def columnCount(self, model_index):
-        """ get the number of columns for the children of the given parent
-
-            @param model_index: QModelIndex*
-
-            @retval column count
-        """
-        if model_index.isValid():
-            return model_index.internalPointer().columnCount()
-        else:
-            return self.root_node.columnCount()
-
-    def data(self, model_index, role):
-        """ get data stored under the given role for the item referred to by the index
-
-            @param model_index: QModelIndex*
-            @param role: QtCore.Qt.*
-
-            @retval data to be displayed
-        """
-        if not model_index.isValid():
-            return None
-
-        item = model_index.internalPointer()
-        column = model_index.column()
-
-        if role == QtCore.Qt.DisplayRole:
-            # display data in corresponding column
-            return item.data(column)
-
-        if (
-            role == QtCore.Qt.ToolTipRole
-            and isinstance(item, (CapaExplorerRuleItem, CapaExplorerRuleMatchItem))
-            and CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION == column
-        ):
-            # show tooltip containing rule source
-            return item.source
-
-        if role == QtCore.Qt.CheckStateRole and column == CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION:
-            # inform view how to display content of checkbox - un/checked
-            return QtCore.Qt.Checked if item.isChecked() else QtCore.Qt.Unchecked
-
-        if role == QtCore.Qt.FontRole and column in (
-            CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS,
-            CapaExplorerDataModel.COLUMN_INDEX_DETAILS,
-        ):
-            # set font for virtual address and details columns
-            font = QtGui.QFont("Courier", weight=QtGui.QFont.Medium)
-            if column == CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS:
-                font.setBold(True)
-            return font
-
-        if (
-            role == QtCore.Qt.FontRole
-            and isinstance(
-                item,
-                (
-                    CapaExplorerRuleItem,
-                    CapaExplorerRuleMatchItem,
-                    CapaExplorerBlockItem,
-                    CapaExplorerFunctionItem,
-                    CapaExplorerFeatureItem,
-                    CapaExplorerSubscopeItem,
-                ),
-            )
-            and column == CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION
-        ):
-            # set bold font for top-level rules
-            font = QtGui.QFont()
-            font.setBold(True)
-            return font
-
-        if role == QtCore.Qt.ForegroundRole and column == CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS:
-            # set color for virtual address column
-            return QtGui.QColor(88, 139, 174)
-
-        if (
-            role == QtCore.Qt.ForegroundRole
-            and isinstance(item, CapaExplorerFeatureItem)
-            and column == CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION
-        ):
-            # set color for feature items
-            return QtGui.QColor(79, 121, 66)
-
-        return None
-
-    def flags(self, model_index):
-        """ get item flags for given index
-
-            @param model_index: QModelIndex*
-
-            @retval QtCore.Qt.ItemFlags
-        """
-        if not model_index.isValid():
-            return QtCore.Qt.NoItemFlags
-
-        return model_index.internalPointer().flags
-
-    def headerData(self, section, orientation, role):
-        """ get data for the given role and section in the header with the specified orientation
-
-            @param section: int
-            @param orientation: QtCore.Qt.Orientation
-            @param role: QtCore.Qt.DisplayRole
-
-            @retval header data list()
-        """
-        if orientation == QtCore.Qt.Horizontal and role == QtCore.Qt.DisplayRole:
-            return self.root_node.data(section)
-
-        return None
-
-    def index(self, row, column, parent):
-        """ get index of the item in the model specified by the given row, column and parent index
-
-            @param row: int
-            @param column: int
-            @param parent: QModelIndex*
-
-            @retval QModelIndex*
-        """
-        if not self.hasIndex(row, column, parent):
-            return QtCore.QModelIndex()
-
-        if not parent.isValid():
-            parent_item = self.root_node
-        else:
-            parent_item = parent.internalPointer()
-
-        child_item = parent_item.child(row)
-
-        if child_item:
-            return self.createIndex(row, column, child_item)
-        else:
-            return QtCore.QModelIndex()
-
-    def parent(self, model_index):
-        """ get parent of the model item with the given index
-
-            if the item has no parent, an invalid QModelIndex* is returned
-
-            @param model_index: QModelIndex*
-
-            @retval QModelIndex*
-        """
-        if not model_index.isValid():
-            return QtCore.QModelIndex()
-
-        child = model_index.internalPointer()
-        parent = child.parent()
-
-        if parent == self.root_node:
-            return QtCore.QModelIndex()
-
-        return self.createIndex(parent.row(), 0, parent)
-
-    def iterateChildrenIndexFromRootIndex(self, model_index, ignore_root=True):
-        """ depth-first traversal of child nodes
-
-            @param model_index: QModelIndex*
-            @param ignore_root: if set, do not return root index
-
-            @retval yield QModelIndex*
-        """
-        visited = set()
-        stack = deque((model_index,))
-
-        while True:
-            try:
-                child_index = stack.pop()
-            except IndexError:
-                break
-
-            if child_index not in visited:
-                if not ignore_root or child_index is not model_index:
-                    # ignore root
-                    yield child_index
-
-                visited.add(child_index)
-
-                for idx in range(self.rowCount(child_index)):
-                    stack.append(child_index.child(idx, 0))
-
-    def reset_ida_highlighting(self, item, checked):
-        """ reset IDA highlight for an item
-
-            @param item: capa explorer item
-            @param checked: indicates item is or not checked
-        """
-        if not isinstance(
-            item, (CapaExplorerStringViewItem, CapaExplorerInstructionViewItem, CapaExplorerByteViewItem)
-        ):
-            # ignore other item types
-            return
-
-        curr_highlight = idc.get_color(item.location, idc.CIC_ITEM)
-
-        if checked:
-            # item checked - record current highlight and set to new
-            item.ida_highlight = curr_highlight
-            idc.set_color(item.location, idc.CIC_ITEM, DEFAULT_HIGHLIGHT)
-        else:
-            # item unchecked - reset highlight
-            if curr_highlight != DEFAULT_HIGHLIGHT:
-                # user modified highlight - record new highlight and do not modify
-                item.ida_highlight = curr_highlight
-            else:
-                # reset highlight to previous
-                idc.set_color(item.location, idc.CIC_ITEM, item.ida_highlight)
-
-    def setData(self, model_index, value, role):
-        """ set the role data for the item at index to value
-
-            @param model_index: QModelIndex*
-            @param value: QVariant*
-            @param role: QtCore.Qt.EditRole
-
-            @retval True/False
-        """
-        if not model_index.isValid():
-            return False
-
-        if (
-            role == QtCore.Qt.CheckStateRole
-            and model_index.column() == CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION
-        ):
-            # user un/checked box - un/check parent and children
-            for child_index in self.iterateChildrenIndexFromRootIndex(model_index, ignore_root=False):
-                child_index.internalPointer().setChecked(value)
-                self.reset_ida_highlighting(child_index.internalPointer(), value)
-                self.dataChanged.emit(child_index, child_index)
-            return True
-
-        if (
-            role == QtCore.Qt.EditRole
-            and value
-            and model_index.column() == CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION
-            and isinstance(model_index.internalPointer(), CapaExplorerFunctionItem)
-        ):
-            # user renamed function - update IDA database and data model
-            old_name = model_index.internalPointer().info
-            new_name = str(value)
-
-            if idaapi.set_name(model_index.internalPointer().location, new_name):
-                # success update IDA database - update data model
-                self.update_function_name(old_name, new_name)
-                return True
-
-        # no handle
-        return False
-
-    def rowCount(self, model_index):
-        """ get the number of rows under the given parent
-
-            when the parent is valid it means that is returning the number of
-            children of parent
-
-            @param model_index: QModelIndex*
-
-            @retval row count
-        """
-        if model_index.column() > 0:
-            return 0
-
-        if not model_index.isValid():
-            item = self.root_node
-        else:
-            item = model_index.internalPointer()
-
-        return item.childCount()
-
-    def render_capa_doc_statement_node(self, parent, statement, locations, doc):
-        """ render capa statement read from doc
-
-            @param parent: parent to which new child is assigned
-            @param statement: statement read from doc
-            @param locations: locations of children (applies to range only?)
-            @param doc: capa result doc
-
-            "statement": {
-                "type": "or"
-            },
-        """
-        if statement["type"] in ("and", "or", "optional"):
-            return CapaExplorerDefaultItem(parent, statement["type"])
-        elif statement["type"] == "not":
-            # TODO: do we display 'not'
-            pass
-        elif statement["type"] == "some":
-            return CapaExplorerDefaultItem(parent, statement["count"] + " or more")
-        elif statement["type"] == "range":
-            # `range` is a weird node, its almost a hybrid of statement + feature.
-            # it is a specific feature repeated multiple times.
-            # there's no additional logic in the feature part, just the existence of a feature.
-            # so, we have to inline some of the feature rendering here.
-            display = "count(%s): " % self.capa_doc_feature_to_display(statement["child"])
-
-            if statement["max"] == statement["min"]:
-                display += "%d" % (statement["min"])
-            elif statement["min"] == 0:
-                display += "%d or fewer" % (statement["max"])
-            elif statement["max"] == (1 << 64 - 1):
-                display += "%d or more" % (statement["min"])
-            else:
-                display += "between %d and %d" % (statement["min"], statement["max"])
-
-            parent2 = CapaExplorerFeatureItem(parent, display=display)
-
-            for location in locations:
-                # for each location render child node for range statement
-                self.render_capa_doc_feature(parent2, statement["child"], location, doc)
-
-            return parent2
-        elif statement["type"] == "subscope":
-            return CapaExplorerSubscopeItem(parent, statement[statement["type"]])
-        else:
-            raise RuntimeError("unexpected match statement type: " + str(statement))
-
-    def render_capa_doc_match(self, parent, match, doc):
-        """ render capa match read from doc
-
-            @param parent: parent node to which new child is assigned
-            @param match: match read from doc
-            @param doc: capa result doc
-
-            "matches": {
-                "0": {
-                    "children": [],
-                    "locations": [
-                        4317184
-                    ],
-                    "node": {
-                        "feature": {
-                            "section": ".rsrc",
-                            "type": "section"
-                        },
-                        "type": "feature"
-                    },
-                    "success": true
-                }
-            },
-        """
-        if not match["success"]:
-            # TODO: display failed branches at some point? Help with debugging rules?
-            return
-
-        # optional statement with no successful children is empty
-        if match["node"].get("statement", {}).get("type") == "optional" and not any(
-            map(lambda m: m["success"], match["children"])
-        ):
-            return
-
-        if match["node"]["type"] == "statement":
-            parent2 = self.render_capa_doc_statement_node(
-                parent, match["node"]["statement"], match.get("locations", []), doc
-            )
-        elif match["node"]["type"] == "feature":
-            parent2 = self.render_capa_doc_feature_node(
-                parent, match["node"]["feature"], match.get("locations", []), doc
-            )
-        else:
-            raise RuntimeError("unexpected node type: " + str(match["node"]["type"]))
-
-        for child in match.get("children", []):
-            self.render_capa_doc_match(parent2, child, doc)
-
-    def render_capa_doc(self, doc):
-        """ render capa features specified in doc
-
-            @param doc: capa result doc
-        """
-        # inform model that changes are about to occur
-        self.beginResetModel()
-
-        for rule in rutils.capability_rules(doc):
-            parent = CapaExplorerRuleItem(self.root_node, rule["meta"]["name"], len(rule["matches"]), rule["source"])
-
-            for (location, match) in doc["rules"][rule["meta"]["name"]]["matches"].items():
-                if rule["meta"]["scope"] == capa.rules.FILE_SCOPE:
-                    parent2 = parent
-                elif rule["meta"]["scope"] == capa.rules.FUNCTION_SCOPE:
-                    parent2 = CapaExplorerFunctionItem(parent, location)
-                elif rule["meta"]["scope"] == capa.rules.BASIC_BLOCK_SCOPE:
-                    parent2 = CapaExplorerBlockItem(parent, location)
-                else:
-                    raise RuntimeError("unexpected rule scope: " + str(rule["meta"]["scope"]))
-
-                self.render_capa_doc_match(parent2, match, doc)
-
-        # inform model changes have ended
-        self.endResetModel()
-
-    def capa_doc_feature_to_display(self, feature):
-        """ convert capa doc feature type string to display string for ui
-
-            @param feature: capa feature read from doc
-
-            Example:
-                "feature": {
-                    "bytes": "01 14 02 00 00 00 00 00 C0 00 00 00 00 00 00 46",
-                    "description": "CLSID_ShellLink",
-                    "type": "bytes"
-                }
-
-                bytes(01 14 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_ShellLink)
-        """
-        if feature[feature["type"]]:
-            if feature.get("description", ""):
-                return "%s(%s = %s)" % (feature["type"], feature[feature["type"]], feature["description"])
-            else:
-                return "%s(%s)" % (feature["type"], feature[feature["type"]])
-        else:
-            return "%s" % feature["type"]
-
-    def render_capa_doc_feature_node(self, parent, feature, locations, doc):
-        """ process capa doc feature node
-
-            @param parent: parent node to which child is assigned
-            @param feature: capa doc feature node
-            @param locations: locations identified for feature
-            @param doc: capa doc
-
-            Example:
-              "feature": {
-                "description": "FILE_WRITE_DATA",
-                "number": "0x2",
-                "type": "number"
-              }
-        """
-        display = self.capa_doc_feature_to_display(feature)
-
-        if len(locations) == 1:
-            # only one location for feature so no need to nest children
-            parent2 = self.render_capa_doc_feature(parent, feature, next(iter(locations)), doc, display=display,)
-        else:
-            # feature has multiple children, nest  under one parent feature node
-            parent2 = CapaExplorerFeatureItem(parent, display)
-
-            for location in sorted(locations):
-                self.render_capa_doc_feature(parent2, feature, location, doc)
-
-        return parent2
-
-    def render_capa_doc_feature(self, parent, feature, location, doc, display="-"):
-        """ render capa feature read from doc
-
-            @param parent: parent node to which new child is assigned
-            @param feature: feature read from doc
-            @param doc: capa feature doc
-            @param location: address of feature
-            @param display: text to display in plugin ui
-
-            Example:
-              "feature": {
-                "description": "FILE_WRITE_DATA",
-                "number": "0x2",
-                "type": "number"
-              }
-        """
-        # special handling for characteristic pending type
-        if feature["type"] == "characteristic":
-            if feature[feature["type"]] in ("embedded pe",):
-                return CapaExplorerByteViewItem(parent, display, location)
-
-            if feature[feature["type"]] in ("loop", "recursive call", "tight loop", "switch"):
-                return CapaExplorerFeatureItem(parent, display=display)
-
-            # default to instruction view for all other characteristics
-            return CapaExplorerInstructionViewItem(parent, display, location)
-
-        if feature["type"] == "match":
-            # display content of rule for all rule matches
-            return CapaExplorerRuleMatchItem(
-                parent, display, source=doc["rules"].get(feature[feature["type"]], {}).get("source", "")
-            )
-
-        if feature["type"] == "regex":
-            return CapaExplorerFeatureItem(parent, display, location, details=feature["match"])
-
-        if feature["type"] == "basicblock":
-            return CapaExplorerBlockItem(parent, location)
-
-        if feature["type"] in ("bytes", "api", "mnemonic", "number", "offset"):
-            # display instruction preview
-            return CapaExplorerInstructionViewItem(parent, display, location)
-
-        if feature["type"] in ("section",):
-            # display byte preview
-            return CapaExplorerByteViewItem(parent, display, location)
-
-        if feature["type"] in ("string",):
-            # display string preview
-            return CapaExplorerStringViewItem(parent, display, location)
-
-        if feature["type"] in ("import", "export"):
-            # display no preview
-            return CapaExplorerFeatureItem(parent, display=display)
-
-        raise RuntimeError("unexpected feature type: " + str(feature["type"]))
-
-    def update_function_name(self, old_name, new_name):
-        """ update all instances of old function name with new function name
-
-            @param old_name: previous function name
-            @param new_name: new function name
-        """
-        # create empty root index for search
-        root_index = self.index(0, 0, QtCore.QModelIndex())
-
-        # convert name to view format for matching e.g. function(my_function)
-        old_name = CapaExplorerFunctionItem.fmt % old_name
-
-        # recursive search for all instances of old function name
-        for model_index in self.match(
-            root_index, QtCore.Qt.DisplayRole, old_name, hits=-1, flags=QtCore.Qt.MatchRecursive
-        ):
-            if not isinstance(model_index.internalPointer(), CapaExplorerFunctionItem):
-                continue
-
-            # replace old function name with new function name and emit change
-            model_index.internalPointer().info = new_name
-            self.dataChanged.emit(model_index, model_index)

capa/ida/explorer/proxy.py

@@ -1,83 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-from PyQt5 import QtCore
-
-from capa.ida.explorer.model import CapaExplorerDataModel
-
-
-class CapaExplorerSortFilterProxyModel(QtCore.QSortFilterProxyModel):
-    def __init__(self, parent=None):
-        """ """
-        super(CapaExplorerSortFilterProxyModel, self).__init__(parent)
-
-    def lessThan(self, left, right):
-        """ true if the value of the left item is less than value of right item
-
-            @param left: QModelIndex*
-            @param right: QModelIndex*
-
-            @retval True/False
-        """
-        ldata = left.internalPointer().data(left.column())
-        rdata = right.internalPointer().data(right.column())
-
-        if (
-            ldata
-            and rdata
-            and left.column() == CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS
-            and left.column() == right.column()
-        ):
-            # convert virtual address before compare
-            return int(ldata, 16) < int(rdata, 16)
-        else:
-            # compare as lowercase
-            return ldata.lower() < rdata.lower()
-
-    def filterAcceptsRow(self, row, parent):
-        """ true if the item in the row indicated by the given row and parent
-            should be included in the model; otherwise returns false
-
-            @param row: int
-            @param parent: QModelIndex*
-
-            @retval True/False
-        """
-        if self.filter_accepts_row_self(row, parent):
-            return True
-
-        alpha = parent
-        while alpha.isValid():
-            if self.filter_accepts_row_self(alpha.row(), alpha.parent()):
-                return True
-            alpha = alpha.parent()
-
-        if self.index_has_accepted_children(row, parent):
-            return True
-
-        return False
-
-    def add_single_string_filter(self, column, string):
-        """ add fixed string filter
-
-            @param column: key column
-            @param string: string to sort
-        """
-        self.setFilterKeyColumn(column)
-        self.setFilterFixedString(string)
-
-    def index_has_accepted_children(self, row, parent):
-        """ """
-        model_index = self.sourceModel().index(row, 0, parent)
-
-        if model_index.isValid():
-            for idx in range(self.sourceModel().rowCount(model_index)):
-                if self.filter_accepts_row_self(idx, model_index):
-                    return True
-                if self.index_has_accepted_children(idx, model_index):
-                    return True
-
-        return False
-
-    def filter_accepts_row_self(self, row, parent):
-        """ """
-        return super(CapaExplorerSortFilterProxyModel, self).filterAcceptsRow(row, parent)

capa/ida/explorer/view.py

@@ -1,256 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import idc
-import idaapi
-from PyQt5 import QtGui, QtCore, QtWidgets
-
-from capa.ida.explorer.item import CapaExplorerRuleItem, CapaExplorerFunctionItem
-from capa.ida.explorer.model import CapaExplorerDataModel
-
-
-class CapaExplorerQtreeView(QtWidgets.QTreeView):
-    """ capa explorer QTreeView implementation
-
-        view controls UI action responses and displays data from
-        CapaExplorerDataModel
-
-        view does not modify CapaExplorerDataModel directly - data
-        modifications should be implemented in CapaExplorerDataModel
-    """
-
-    def __init__(self, model, parent=None):
-        """ initialize CapaExplorerQTreeView """
-        super(CapaExplorerQtreeView, self).__init__(parent)
-
-        self.setModel(model)
-
-        self.model = model
-        self.parent = parent
-
-        # configure custom UI controls
-        self.setContextMenuPolicy(QtCore.Qt.CustomContextMenu)
-        self.setExpandsOnDoubleClick(False)
-        self.setSortingEnabled(True)
-        self.model.setDynamicSortFilter(False)
-
-        # configure view columns to auto-resize
-        for idx in range(CapaExplorerDataModel.COLUMN_COUNT):
-            self.header().setSectionResizeMode(idx, QtWidgets.QHeaderView.Interactive)
-
-        # connect slots to resize columns when expanded or collapsed
-        self.expanded.connect(self.resize_columns_to_content)
-        self.collapsed.connect(self.resize_columns_to_content)
-
-        # connect slots
-        self.customContextMenuRequested.connect(self.slot_custom_context_menu_requested)
-        self.doubleClicked.connect(self.slot_double_click)
-
-        self.setStyleSheet("QTreeView::item {padding-right: 15 px;padding-bottom: 2 px;}")
-
-    def reset(self):
-        """ reset user interface changes
-
-            called when view should reset any user interface changes
-            made since the last reset e.g. IDA window highlighting
-        """
-        self.collapseAll()
-        self.resize_columns_to_content()
-
-    def resize_columns_to_content(self):
-        """ reset view columns to contents """
-        self.header().resizeSections(QtWidgets.QHeaderView.ResizeToContents)
-
-    def map_index_to_source_item(self, model_index):
-        """ map proxy model index to source model item
-
-            @param model_index: QModelIndex*
-
-            @retval QObject*
-        """
-        return self.model.mapToSource(model_index).internalPointer()
-
-    def send_data_to_clipboard(self, data):
-        """ copy data to the clipboard
-
-            @param data: data to be copied
-        """
-        clip = QtWidgets.QApplication.clipboard()
-        clip.clear(mode=clip.Clipboard)
-        clip.setText(data, mode=clip.Clipboard)
-
-    def new_action(self, display, data, slot):
-        """ create action for context menu
-
-            @param display: text displayed to user in context menu
-            @param data: data passed to slot
-            @param slot: slot to connect
-
-            @retval QAction*
-        """
-        action = QtWidgets.QAction(display, self.parent)
-        action.setData(data)
-        action.triggered.connect(lambda checked: slot(action))
-
-        return action
-
-    def load_default_context_menu_actions(self, data):
-        """ yield actions specific to function custom context menu
-
-            @param data: tuple
-
-            @yield QAction*
-        """
-        default_actions = (
-            ("Copy column", data, self.slot_copy_column),
-            ("Copy row", data, self.slot_copy_row),
-        )
-
-        # add default actions
-        for action in default_actions:
-            yield self.new_action(*action)
-
-    def load_function_context_menu_actions(self, data):
-        """ yield actions specific to function custom context menu
-
-            @param data: tuple
-
-            @yield QAction*
-        """
-        function_actions = (("Rename function", data, self.slot_rename_function),)
-
-        # add function actions
-        for action in function_actions:
-            yield self.new_action(*action)
-
-        # add default actions
-        for action in self.load_default_context_menu_actions(data):
-            yield action
-
-    def load_default_context_menu(self, pos, item, model_index):
-        """ create default custom context menu
-
-            creates custom context menu containing default actions
-
-            @param pos: TODO
-            @param item: TODO
-            @param model_index: TODO
-
-            @retval QMenu*
-        """
-        menu = QtWidgets.QMenu()
-
-        for action in self.load_default_context_menu_actions((pos, item, model_index)):
-            menu.addAction(action)
-
-        return menu
-
-    def load_function_item_context_menu(self, pos, item, model_index):
-        """ create function custom context menu
-
-            creates custom context menu containing actions specific to functions
-            and the default actions
-
-            @param pos: TODO
-            @param item: TODO
-            @param model_index: TODO
-
-            @retval QMenu*
-        """
-        menu = QtWidgets.QMenu()
-
-        for action in self.load_function_context_menu_actions((pos, item, model_index)):
-            menu.addAction(action)
-
-        return menu
-
-    def show_custom_context_menu(self, menu, pos):
-        """ display custom context menu in view
-
-            @param menu: TODO
-            @param pos: TODO
-        """
-        if menu:
-            menu.exec_(self.viewport().mapToGlobal(pos))
-
-    def slot_copy_column(self, action):
-        """ slot connected to custom context menu
-
-            allows user to select a column and copy the data
-            to clipboard
-
-            @param action: QAction*
-        """
-        _, item, model_index = action.data()
-        self.send_data_to_clipboard(item.data(model_index.column()))
-
-    def slot_copy_row(self, action):
-        """ slot connected to custom context menu
-
-            allows user to select a row and copy the space-delimited
-            data to clipboard
-
-            @param action: QAction*
-        """
-        _, item, _ = action.data()
-        self.send_data_to_clipboard(str(item))
-
-    def slot_rename_function(self, action):
-        """ slot connected to custom context menu
-
-            allows user to select a edit a function name and push
-            changes to IDA
-
-            @param action: QAction*
-        """
-        _, item, model_index = action.data()
-
-        # make item temporary edit, reset after user is finished
-        item.setIsEditable(True)
-        self.edit(model_index)
-        item.setIsEditable(False)
-
-    def slot_custom_context_menu_requested(self, pos):
-        """ slot connected to custom context menu request
-
-            displays custom context menu to user containing action
-            relevant to the data item selected
-
-            @param pos: TODO
-        """
-        model_index = self.indexAt(pos)
-
-        if not model_index.isValid():
-            return
-
-        item = self.map_index_to_source_item(model_index)
-        column = model_index.column()
-        menu = None
-
-        if CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION == column and isinstance(item, CapaExplorerFunctionItem):
-            # user hovered function item
-            menu = self.load_function_item_context_menu(pos, item, model_index)
-        else:
-            # user hovered default item
-            menu = self.load_default_context_menu(pos, item, model_index)
-
-        # show custom context menu at view position
-        self.show_custom_context_menu(menu, pos)
-
-    def slot_double_click(self, model_index):
-        """ slot connected to double click event
-
-            @param model_index: QModelIndex*
-        """
-        if not model_index.isValid():
-            return
-
-        item = self.map_index_to_source_item(model_index)
-        column = model_index.column()
-
-        if CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS == column and item.location:
-            # user double-clicked virtual address column - navigate IDA to address
-            idc.jumpto(item.location)
-
-        if CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION == column:
-            # user double-clicked information column - un/expand
-            self.collapse(model_index) if self.isExpanded(model_index) else self.expand(model_index)

capa/ida/helpers.py

@@ -0,0 +1,252 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+import datetime
+import contextlib
+from typing import List, Optional
+from pathlib import Path
+
+import idc
+import idaapi
+import idautils
+import ida_bytes
+import ida_loader
+from netnode import netnode
+
+import capa
+import capa.version
+import capa.render.utils as rutils
+import capa.features.common
+import capa.features.freeze
+import capa.render.result_document as rdoc
+from capa.features.address import AbsoluteVirtualAddress
+
+logger = logging.getLogger("capa")
+
+# file type as returned by idainfo.file_type
+SUPPORTED_FILE_TYPES = (
+    idaapi.f_PE,
+    idaapi.f_ELF,
+    idaapi.f_BIN,
+    idaapi.f_COFF,
+    # idaapi.f_MACHO,
+)
+
+# arch type as returned by idainfo.procname
+SUPPORTED_ARCH_TYPES = ("metapc",)
+
+CAPA_NETNODE = f"$ com.mandiant.capa.v{capa.version.__version__}"
+NETNODE_RESULTS = "results"
+NETNODE_RULES_CACHE_ID = "rules-cache-id"
+
+
+def inform_user_ida_ui(message):
+    # this isn't a logger, this is IDA's logging facility
+    idaapi.info(f"{message}. Please refer to IDA Output window for more information.")  # noqa: G004
+
+
+def is_supported_ida_version():
+    version = float(idaapi.get_kernel_version())
+    if version < 7.4 or version >= 9:
+        warning_msg = "This plugin does not support your IDA Pro version"
+        logger.warning(warning_msg)
+        logger.warning("Your IDA Pro version is: %s. Supported versions are: IDA >= 7.4 and IDA < 9.0.", version)
+        return False
+    return True
+
+
+def is_supported_file_type():
+    file_info = idaapi.get_inf_structure()
+    if file_info.filetype not in SUPPORTED_FILE_TYPES:
+        logger.error("-" * 80)
+        logger.error(" Input file does not appear to be a supported file type.")
+        logger.error(" ")
+        logger.error(
+            " capa currently only supports analyzing PE, ELF, or binary files containing x86 (32- and 64-bit) shellcode."
+        )
+        logger.error(" If you don't know the input file type, you can try using the `file` utility to guess it.")
+        logger.error("-" * 80)
+        return False
+    return True
+
+
+def is_supported_arch_type():
+    file_info = idaapi.get_inf_structure()
+    if file_info.procname not in SUPPORTED_ARCH_TYPES or not any((file_info.is_32bit(), file_info.is_64bit())):
+        logger.error("-" * 80)
+        logger.error(" Input file does not appear to target a supported architecture.")
+        logger.error(" ")
+        logger.error(" capa currently only supports analyzing x86 (32- and 64-bit).")
+        logger.error("-" * 80)
+        return False
+    return True
+
+
+def get_disasm_line(va):
+    """ """
+    return idc.generate_disasm_line(va, idc.GENDSM_FORCE_CODE)
+
+
+def is_func_start(ea):
+    """check if function stat exists at virtual address"""
+    f = idaapi.get_func(ea)
+    return f and f.start_ea == ea
+
+
+def get_func_start_ea(ea):
+    """ """
+    f = idaapi.get_func(ea)
+    return f if f is None else f.start_ea
+
+
+def get_file_md5():
+    """ """
+    md5 = idautils.GetInputFileMD5()
+    if not isinstance(md5, str):
+        md5 = capa.features.common.bytes_to_str(md5)
+    return md5
+
+
+def get_file_sha256():
+    """ """
+    sha256 = idaapi.retrieve_input_file_sha256()
+    if not isinstance(sha256, str):
+        sha256 = capa.features.common.bytes_to_str(sha256)
+    return sha256
+
+
+def collect_metadata(rules: List[Path]):
+    """ """
+    md5 = get_file_md5()
+    sha256 = get_file_sha256()
+
+    info: idaapi.idainfo = idaapi.get_inf_structure()
+    if info.procname == "metapc" and info.is_64bit():
+        arch = "x86_64"
+    elif info.procname == "metapc" and info.is_32bit():
+        arch = "x86"
+    else:
+        arch = "unknown arch"
+
+    format_name: str = ida_loader.get_file_type_name()
+    if "PE" in format_name:
+        os = "windows"
+    elif "ELF" in format_name:
+        with contextlib.closing(capa.ida.helpers.IDAIO()) as f:
+            os = capa.features.extractors.elf.detect_elf_os(f)
+    else:
+        os = "unknown os"
+
+    return rdoc.Metadata(
+        timestamp=datetime.datetime.now(),
+        version=capa.version.__version__,
+        argv=(),
+        sample=rdoc.Sample(
+            md5=md5,
+            sha1="",  # not easily accessible
+            sha256=sha256,
+            path=idaapi.get_input_file_path(),
+        ),
+        analysis=rdoc.Analysis(
+            format=idaapi.get_file_type_name(),
+            arch=arch,
+            os=os,
+            extractor="ida",
+            rules=tuple(r.resolve().absolute().as_posix() for r in rules),
+            base_address=capa.features.freeze.Address.from_capa(idaapi.get_imagebase()),
+            layout=rdoc.Layout(
+                functions=(),
+                # this is updated after capabilities have been collected.
+                # will look like:
+                #
+                # "functions": { 0x401000: { "matched_basic_blocks": [ 0x401000, 0x401005, ... ] }, ... }
+            ),
+            # ignore these for now - not used by IDA plugin.
+            feature_counts=rdoc.FeatureCounts(file=0, functions=()),
+            library_functions=(),
+        ),
+    )
+
+
+class IDAIO:
+    """
+    An object that acts as a file-like object,
+    using bytes from the current IDB workspace.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.offset = 0
+
+    def seek(self, offset, whence=0):
+        assert whence == 0
+        self.offset = offset
+
+    def read(self, size):
+        ea = ida_loader.get_fileregion_ea(self.offset)
+        if ea == idc.BADADDR:
+            logger.debug("cannot read 0x%x bytes at 0x%x (ea: BADADDR)", size, self.offset)
+            return b""
+
+        logger.debug("reading 0x%x bytes at 0x%x (ea: 0x%x)", size, self.offset, ea)
+
+        # get_bytes returns None on error, for consistency with read always return bytes
+        return ida_bytes.get_bytes(ea, size) or b""
+
+    def close(self):
+        return
+
+
+def save_cached_results(resdoc):
+    logger.debug("saving cached capa results to netnode '%s'", CAPA_NETNODE)
+    n = netnode.Netnode(CAPA_NETNODE)
+    n[NETNODE_RESULTS] = resdoc.json()
+
+
+def idb_contains_cached_results() -> bool:
+    try:
+        n = netnode.Netnode(CAPA_NETNODE)
+        return bool(n.get(NETNODE_RESULTS))
+    except netnode.NetnodeCorruptError as e:
+        logger.exception(str(e))
+        return False
+
+
+def load_and_verify_cached_results() -> Optional[rdoc.ResultDocument]:
+    """verifies that cached results have valid (mapped) addresses for the current database"""
+    logger.debug("loading cached capa results from netnode '%s'", CAPA_NETNODE)
+
+    n = netnode.Netnode(CAPA_NETNODE)
+    doc = rdoc.ResultDocument.model_validate_json(n[NETNODE_RESULTS])
+
+    for rule in rutils.capability_rules(doc):
+        for location_, _ in rule.matches:
+            location = location_.to_capa()
+            if isinstance(location, AbsoluteVirtualAddress):
+                ea = int(location)
+                if not idaapi.is_mapped(ea):
+                    logger.error("cached address %s is not a valid location in this database", hex(ea))
+                    return None
+    return doc
+
+
+def save_rules_cache_id(ruleset_id):
+    logger.debug("saving ruleset ID to netnode '%s'", CAPA_NETNODE)
+    n = netnode.Netnode(CAPA_NETNODE)
+    n[NETNODE_RULES_CACHE_ID] = ruleset_id
+
+
+def load_rules_cache_id():
+    n = netnode.Netnode(CAPA_NETNODE)
+    return n[NETNODE_RULES_CACHE_ID]
+
+
+def delete_cached_results():
+    logger.debug("deleting cached capa data")
+    n = netnode.Netnode(CAPA_NETNODE)
+    del n[NETNODE_RESULTS]

capa/ida/helpers/__init__.py

@@ -1,71 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import logging
-import datetime
-
-import idc
-import idaapi
-import idautils
-
-import capa
-
-logger = logging.getLogger("capa")
-
-# file type names as returned by idaapi.get_file_type_name()
-SUPPORTED_FILE_TYPES = [
-    "Portable executable for 80386 (PE)",
-    "Portable executable for AMD64 (PE)",
-    "Binary file",  # x86/AMD64 shellcode support
-]
-
-
-def inform_user_ida_ui(message):
-    idaapi.info("%s. Please refer to IDA Output window for more information." % message)
-
-
-def is_supported_file_type():
-    file_type = idaapi.get_file_type_name()
-    if file_type not in SUPPORTED_FILE_TYPES:
-        logger.error("-" * 80)
-        logger.error(" Input file does not appear to be a PE file.")
-        logger.error(" ")
-        logger.error(
-            " capa currently only supports analyzing PE files (or binary files containing x86/AMD64 shellcode) with IDA."
-        )
-        logger.error(" If you don't know the input file type, you can try using the `file` utility to guess it.")
-        logger.error("-" * 80)
-        inform_user_ida_ui("capa does not support the format of this file")
-        return False
-    return True
-
-
-def get_disasm_line(va):
-    """ """
-    return idc.generate_disasm_line(va, idc.GENDSM_FORCE_CODE)
-
-
-def is_func_start(ea):
-    """ check if function stat exists at virtual address """
-    f = idaapi.get_func(ea)
-    return f and f.start_ea == ea
-
-
-def get_func_start_ea(ea):
-    """ """
-    f = idaapi.get_func(ea)
-    return f if f is None else f.start_ea
-
-
-def collect_metadata():
-    return {
-        "timestamp": datetime.datetime.now().isoformat(),
-        # "argv" is not relevant here
-        "sample": {
-            "md5": capa.features.bytes_to_str(idautils.GetInputFileMD5()),
-            # "sha1" not easily accessible
-            "sha256": capa.features.bytes_to_str(idaapi.retrieve_input_file_sha256()),
-            "path": idaapi.get_input_file_path(),
-        },
-        "analysis": {"format": idaapi.get_file_type_name(), "extractor": "ida",},
-        "version": capa.version.__version__,
-    }

capa/ida/ida_capa_explorer.py

@@ -1,564 +0,0 @@
-# Copyright (C) 2020 FireEye, Inc. All Rights Reserved.
-
-import os
-import json
-import logging
-import collections
-
-import idaapi
-from PyQt5 import QtGui, QtCore, QtWidgets
-
-import capa.main
-import capa.rules
-import capa.ida.helpers
-import capa.render.utils as rutils
-import capa.features.extractors.ida
-from capa.ida.explorer.view import CapaExplorerQtreeView
-from capa.ida.explorer.model import CapaExplorerDataModel
-from capa.ida.explorer.proxy import CapaExplorerSortFilterProxyModel
-
-PLUGIN_NAME = "capa explorer"
-
-logger = logging.getLogger("capa")
-
-
-class CapaExplorerIdaHooks(idaapi.UI_Hooks):
-    def __init__(self, screen_ea_changed_hook, action_hooks):
-        """ facilitate IDA UI hooks
-
-            @param screen_ea_changed_hook: function hook for IDA screen ea changed
-            @param action_hooks: dict of IDA action handles
-        """
-        super(CapaExplorerIdaHooks, self).__init__()
-
-        self.screen_ea_changed_hook = screen_ea_changed_hook
-        self.process_action_hooks = action_hooks
-        self.process_action_handle = None
-        self.process_action_meta = {}
-
-    def preprocess_action(self, name):
-        """ called prior to action completed
-
-            @param name: name of action defined by idagui.cfg
-
-            @retval must be 0
-        """
-        self.process_action_handle = self.process_action_hooks.get(name, None)
-
-        if self.process_action_handle:
-            self.process_action_handle(self.process_action_meta)
-
-        # must return 0 for IDA
-        return 0
-
-    def postprocess_action(self):
-        """ called after action completed """
-        if not self.process_action_handle:
-            return
-
-        self.process_action_handle(self.process_action_meta, post=True)
-        self.reset()
-
-    def screen_ea_changed(self, curr_ea, prev_ea):
-        """ called after screen location is changed
-
-            @param curr_ea: current location
-            @param prev_ea: prev location
-        """
-        self.screen_ea_changed_hook(idaapi.get_current_widget(), curr_ea, prev_ea)
-
-    def reset(self):
-        """ reset internal state """
-        self.process_action_handle = None
-        self.process_action_meta.clear()
-
-
-class CapaExplorerForm(idaapi.PluginForm):
-    def __init__(self):
-        """ """
-        super(CapaExplorerForm, self).__init__()
-
-        self.form_title = PLUGIN_NAME
-        self.file_loc = __file__
-
-        self.parent = None
-        self.ida_hooks = None
-        self.doc = None
-
-        # models
-        self.model_data = None
-        self.model_proxy = None
-
-        # user interface elements
-        self.view_limit_results_by_function = None
-        self.view_tree = None
-        self.view_summary = None
-        self.view_attack = None
-        self.view_tabs = None
-        self.view_menu_bar = None
-
-    def OnCreate(self, form):
-        """ """
-        self.parent = self.FormToPyQtWidget(form)
-        self.load_interface()
-        self.load_capa_results()
-        self.load_ida_hooks()
-
-        self.view_tree.reset()
-
-        logger.info("form created.")
-
-    def Show(self):
-        """ """
-        return idaapi.PluginForm.Show(
-            self, self.form_title, options=(idaapi.PluginForm.WOPN_TAB | idaapi.PluginForm.WCLS_CLOSE_LATER)
-        )
-
-    def OnClose(self, form):
-        """ form is closed """
-        self.unload_ida_hooks()
-        self.ida_reset()
-
-        logger.info("form closed.")
-
-    def load_interface(self):
-        """ load user interface """
-        # load models
-        self.model_data = CapaExplorerDataModel()
-        self.model_proxy = CapaExplorerSortFilterProxyModel()
-        self.model_proxy.setSourceModel(self.model_data)
-
-        # load tree
-        self.view_tree = CapaExplorerQtreeView(self.model_proxy, self.parent)
-
-        # load summary table
-        self.load_view_summary()
-        self.load_view_attack()
-
-        # load parent tab and children tab views
-        self.load_view_tabs()
-        self.load_view_checkbox_limit_by()
-        self.load_view_summary_tab()
-        self.load_view_attack_tab()
-        self.load_view_tree_tab()
-
-        # load menu bar and sub menus
-        self.load_view_menu_bar()
-        self.load_file_menu()
-
-        # load parent view
-        self.load_view_parent()
-
-    def load_view_tabs(self):
-        """ load tabs """
-        tabs = QtWidgets.QTabWidget()
-        self.view_tabs = tabs
-
-    def load_view_menu_bar(self):
-        """ load menu bar """
-        bar = QtWidgets.QMenuBar()
-        self.view_menu_bar = bar
-
-    def load_view_summary(self):
-        """ load capa summary table """
-        table_headers = [
-            "Capability",
-            "Namespace",
-        ]
-
-        table = QtWidgets.QTableWidget()
-
-        table.setColumnCount(len(table_headers))
-        table.verticalHeader().setVisible(False)
-        table.setSortingEnabled(False)
-        table.setEditTriggers(QtWidgets.QAbstractItemView.NoEditTriggers)
-        table.setFocusPolicy(QtCore.Qt.NoFocus)
-        table.setSelectionMode(QtWidgets.QAbstractItemView.NoSelection)
-        table.setHorizontalHeaderLabels(table_headers)
-        table.horizontalHeader().setDefaultAlignment(QtCore.Qt.AlignLeft)
-        table.setShowGrid(False)
-        table.setStyleSheet("QTableWidget::item { padding: 25px; }")
-
-        self.view_summary = table
-
-    def load_view_attack(self):
-        """ load MITRE ATT&CK table """
-        table_headers = [
-            "ATT&CK Tactic",
-            "ATT&CK Technique ",
-        ]
-
-        table = QtWidgets.QTableWidget()
-
-        table.setColumnCount(len(table_headers))
-        table.verticalHeader().setVisible(False)
-        table.setSortingEnabled(False)
-        table.setEditTriggers(QtWidgets.QAbstractItemView.NoEditTriggers)
-        table.setFocusPolicy(QtCore.Qt.NoFocus)
-        table.setSelectionMode(QtWidgets.QAbstractItemView.NoSelection)
-        table.setHorizontalHeaderLabels(table_headers)
-        table.horizontalHeader().setDefaultAlignment(QtCore.Qt.AlignLeft)
-        table.setShowGrid(False)
-        table.setStyleSheet("QTableWidget::item { padding: 25px; }")
-
-        self.view_attack = table
-
-    def load_view_checkbox_limit_by(self):
-        """ load limit results by function checkbox """
-        check = QtWidgets.QCheckBox("Limit results to current function")
-        check.setChecked(False)
-        check.stateChanged.connect(self.slot_checkbox_limit_by_changed)
-
-        self.view_limit_results_by_function = check
-
-    def load_view_parent(self):
-        """ load view parent """
-        layout = QtWidgets.QVBoxLayout()
-
-        layout.addWidget(self.view_tabs)
-        layout.setMenuBar(self.view_menu_bar)
-
-        self.parent.setLayout(layout)
-
-    def load_view_tree_tab(self):
-        """ load capa tree tab view """
-        layout = QtWidgets.QVBoxLayout()
-        layout.addWidget(self.view_limit_results_by_function)
-        layout.addWidget(self.view_tree)
-
-        tab = QtWidgets.QWidget()
-        tab.setLayout(layout)
-
-        self.view_tabs.addTab(tab, "Tree View")
-
-    def load_view_summary_tab(self):
-        """ load capa summary tab view """
-        layout = QtWidgets.QVBoxLayout()
-        layout.addWidget(self.view_summary)
-
-        tab = QtWidgets.QWidget()
-        tab.setLayout(layout)
-
-        self.view_tabs.addTab(tab, "Summary")
-
-    def load_view_attack_tab(self):
-        """ load MITRE ATT&CK tab view """
-        layout = QtWidgets.QVBoxLayout()
-        layout.addWidget(self.view_attack)
-
-        tab = QtWidgets.QWidget()
-        tab.setLayout(layout)
-
-        self.view_tabs.addTab(tab, "MITRE")
-
-    def load_file_menu(self):
-        """ load file menu actions """
-        actions = (
-            ("Reset view", "Reset plugin view", self.reset),
-            ("Run analysis", "Run capa analysis on current database", self.reload),
-            ("Export results...", "Export capa results as JSON file", self.export_json),
-        )
-
-        menu = self.view_menu_bar.addMenu("File")
-        for (name, _, handle) in actions:
-            action = QtWidgets.QAction(name, self.parent)
-            action.triggered.connect(handle)
-            menu.addAction(action)
-
-    def export_json(self):
-        """ export capa results as JSON file """
-        if not self.doc:
-            idaapi.info("No capa results to export.")
-            return
-        path = idaapi.ask_file(True, "*.json", "Choose file")
-        if os.path.exists(path) and 1 != idaapi.ask_yn(1, "File already exists. Overwrite?"):
-            return
-        with open(path, "wb") as export_file:
-            export_file.write(
-                json.dumps(self.doc, sort_keys=True, cls=capa.render.CapaJsonObjectEncoder).encode("utf-8")
-            )
-
-    def load_ida_hooks(self):
-        """ load IDA Pro UI hooks """
-        action_hooks = {
-            "MakeName": self.ida_hook_rename,
-            "EditFunction": self.ida_hook_rename,
-        }
-
-        self.ida_hooks = CapaExplorerIdaHooks(self.ida_hook_screen_ea_changed, action_hooks)
-        self.ida_hooks.hook()
-
-    def unload_ida_hooks(self):
-        """ unload IDA Pro UI hooks """
-        if self.ida_hooks:
-            self.ida_hooks.unhook()
-
-    def ida_hook_rename(self, meta, post=False):
-        """ hook for IDA rename action
-
-            called twice, once before action and once after
-            action completes
-
-            @param meta: metadata cache
-            @param post: indicates pre or post action
-        """
-        location = idaapi.get_screen_ea()
-        if not location or not capa.ida.helpers.is_func_start(location):
-            return
-
-        curr_name = idaapi.get_name(location)
-
-        if post:
-            # post action update data model w/ current name
-            self.model_data.update_function_name(meta.get("prev_name", ""), curr_name)
-        else:
-            # pre action so save current name for replacement later
-            meta["prev_name"] = curr_name
-
-    def ida_hook_screen_ea_changed(self, widget, new_ea, old_ea):
-        """ hook for IDA screen ea changed
-
-            @param widget: IDA widget type
-            @param new_ea: destination ea
-            @param old_ea: source ea
-         """
-        if not self.view_limit_results_by_function.isChecked():
-            # ignore if checkbox not selected
-            return
-
-        if idaapi.get_widget_type(widget) != idaapi.BWN_DISASM:
-            # ignore views other than asm
-            return
-
-        # attempt to map virtual addresses to function start addresses
-        new_func_start = capa.ida.helpers.get_func_start_ea(new_ea)
-        old_func_start = capa.ida.helpers.get_func_start_ea(old_ea)
-
-        if new_func_start and new_func_start == old_func_start:
-            # navigated within the same function - do nothing
-            return
-
-        if new_func_start:
-            # navigated to new function - filter for function start virtual address
-            match = capa.ida.explorer.item.location_to_hex(new_func_start)
-        else:
-            # navigated to virtual address not in valid function - clear filter
-            match = ""
-
-        # filter on virtual address to avoid updating filter string if function name is changed
-        self.model_proxy.add_single_string_filter(CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS, match)
-        self.view_tree.resize_columns_to_content()
-
-    def load_capa_results(self):
-        """ run capa analysis and render results in UI """
-        logger.info("-" * 80)
-        logger.info(" Using default embedded rules.")
-        logger.info(" ")
-        logger.info(" You can see the current default rule set here:")
-        logger.info("     https://github.com/fireeye/capa-rules")
-        logger.info("-" * 80)
-
-        rules_path = os.path.join(os.path.dirname(self.file_loc), "../..", "rules")
-        rules = capa.main.get_rules(rules_path)
-        rules = capa.rules.RuleSet(rules)
-
-        meta = capa.ida.helpers.collect_metadata()
-
-        capabilities, counts = capa.main.find_capabilities(
-            rules, capa.features.extractors.ida.IdaFeatureExtractor(), True
-        )
-        meta["analysis"].update(counts)
-
-        # support binary files specifically for x86/AMD64 shellcode
-        # warn user binary file is loaded but still allow capa to process it
-        # TODO: check specific architecture of binary files based on how user configured IDA processors
-        if idaapi.get_file_type_name() == "Binary file":
-            logger.warning("-" * 80)
-            logger.warning(" Input file appears to be a binary file.")
-            logger.warning(" ")
-            logger.warning(
-                " capa currently only supports analyzing binary files containing x86/AMD64 shellcode with IDA."
-            )
-            logger.warning(
-                " This means the results may be misleading or incomplete if the binary file loaded in IDA is not x86/AMD64."
-            )
-            logger.warning(" If you don't know the input file type, you can try using the `file` utility to guess it.")
-            logger.warning("-" * 80)
-
-            capa.ida.helpers.inform_user_ida_ui("capa encountered warnings during analysis")
-
-        if capa.main.has_file_limitation(rules, capabilities, is_standalone=False):
-            capa.ida.helpers.inform_user_ida_ui("capa encountered warnings during analysis")
-
-        logger.info("analysis completed.")
-
-        self.doc = capa.render.convert_capabilities_to_result_document(meta, rules, capabilities)
-
-        self.model_data.render_capa_doc(self.doc)
-        self.render_capa_doc_summary()
-        self.render_capa_doc_mitre_summary()
-
-        self.set_view_tree_default_sort_order()
-
-        logger.info("render views completed.")
-
-    def set_view_tree_default_sort_order(self):
-        """ set capa tree view default sort order """
-        self.view_tree.sortByColumn(CapaExplorerDataModel.COLUMN_INDEX_RULE_INFORMATION, QtCore.Qt.AscendingOrder)
-
-    def render_capa_doc_summary(self):
-        """ render capa summary results """
-        for (row, rule) in enumerate(rutils.capability_rules(self.doc)):
-            count = len(rule["matches"])
-
-            if count == 1:
-                capability = rule["meta"]["name"]
-            else:
-                capability = "%s (%d matches)" % (rule["meta"]["name"], count)
-
-            self.view_summary.setRowCount(row + 1)
-
-            self.view_summary.setItem(row, 0, self.render_new_table_header_item(capability))
-            self.view_summary.setItem(row, 1, QtWidgets.QTableWidgetItem(rule["meta"]["namespace"]))
-
-        # resize columns to content
-        self.view_summary.resizeColumnsToContents()
-
-    def render_capa_doc_mitre_summary(self):
-        """ render capa MITRE ATT&CK results """
-        tactics = collections.defaultdict(set)
-
-        for rule in rutils.capability_rules(self.doc):
-            if not rule["meta"].get("att&ck"):
-                continue
-
-            for attack in rule["meta"]["att&ck"]:
-                tactic, _, rest = attack.partition("::")
-                if "::" in rest:
-                    technique, _, rest = rest.partition("::")
-                    subtechnique, _, id = rest.rpartition(" ")
-                    tactics[tactic].add((technique, subtechnique, id))
-                else:
-                    technique, _, id = rest.rpartition(" ")
-                    tactics[tactic].add((technique, id))
-
-        column_one = []
-        column_two = []
-
-        for (tactic, techniques) in sorted(tactics.items()):
-            column_one.append(tactic.upper())
-            # add extra space when more than one technique
-            column_one.extend(["" for i in range(len(techniques) - 1)])
-
-            for spec in sorted(techniques):
-                if len(spec) == 2:
-                    technique, id = spec
-                    column_two.append("%s %s" % (technique, id))
-                elif len(spec) == 3:
-                    technique, subtechnique, id = spec
-                    column_two.append("%s::%s %s" % (technique, subtechnique, id))
-                else:
-                    raise RuntimeError("unexpected ATT&CK spec format")
-
-        self.view_attack.setRowCount(max(len(column_one), len(column_two)))
-
-        for row, value in enumerate(column_one):
-            self.view_attack.setItem(row, 0, self.render_new_table_header_item(value))
-
-        for row, value in enumerate(column_two):
-            self.view_attack.setItem(row, 1, QtWidgets.QTableWidgetItem(value))
-
-        # resize columns to content
-        self.view_attack.resizeColumnsToContents()
-
-    def render_new_table_header_item(self, text):
-        """ create new table header item with default style """
-        item = QtWidgets.QTableWidgetItem(text)
-        item.setForeground(QtGui.QColor(88, 139, 174))
-
-        font = QtGui.QFont()
-        font.setBold(True)
-
-        item.setFont(font)
-
-        return item
-
-    def ida_reset(self):
-        """ reset IDA UI """
-        self.model_data.reset()
-        self.view_tree.reset()
-        self.view_limit_results_by_function.setChecked(False)
-        self.set_view_tree_default_sort_order()
-
-    def reload(self):
-        """ reload views and re-run capa analysis """
-        self.ida_reset()
-        self.model_proxy.invalidate()
-        self.model_data.clear()
-        self.view_summary.setRowCount(0)
-        self.load_capa_results()
-
-        logger.info("reload complete.")
-        idaapi.info("%s reload completed." % PLUGIN_NAME)
-
-    def reset(self):
-        """ reset UI elements
-
-            e.g. checkboxes and IDA highlighting
-        """
-        self.ida_reset()
-
-        logger.info("reset completed.")
-        idaapi.info("%s reset completed." % PLUGIN_NAME)
-
-    def slot_menu_bar_hovered(self, action):
-        """ display menu action tooltip
-
-            @param action: QtWidgets.QAction*
-
-            @reference: https://stackoverflow.com/questions/21725119/why-wont-qtooltips-appear-on-qactions-within-a-qmenu
-        """
-        QtWidgets.QToolTip.showText(
-            QtGui.QCursor.pos(), action.toolTip(), self.view_menu_bar, self.view_menu_bar.actionGeometry(action)
-        )
-
-    def slot_checkbox_limit_by_changed(self):
-        """ slot activated if checkbox clicked
-
-            if checked, configure function filter if screen location is located
-            in function, otherwise clear filter
-        """
-        match = ""
-        if self.view_limit_results_by_function.isChecked():
-            location = capa.ida.helpers.get_func_start_ea(idaapi.get_screen_ea())
-            if location:
-                match = capa.ida.explorer.item.location_to_hex(location)
-
-        self.model_proxy.add_single_string_filter(CapaExplorerDataModel.COLUMN_INDEX_VIRTUAL_ADDRESS, match)
-
-        self.view_tree.resize_columns_to_content()
-
-
-def main():
-    """ TODO: move to idaapi.plugin_t class """
-    logging.basicConfig(level=logging.INFO)
-
-    if not capa.ida.helpers.is_supported_file_type():
-        return -1
-
-    global CAPA_EXPLORER_FORM
-
-    try:
-        # there is an instance, reload it
-        CAPA_EXPLORER_FORM
-        CAPA_EXPLORER_FORM.Close()
-        CAPA_EXPLORER_FORM = CapaExplorerForm()
-    except Exception:
-        # there is no instance yet
-        CAPA_EXPLORER_FORM = CapaExplorerForm()
-
-    CAPA_EXPLORER_FORM.Show()
-
-
-if __name__ == "__main__":
-    main()

capa/ida/plugin/README.md

@@ -0,0 +1,126 @@
+![capa explorer](../../../.github/capa-explorer-logo.png)
+
+capa explorer is an IDAPython plugin that integrates the FLARE team's open-source framework, capa, with IDA Pro. capa is a framework that uses a well-defined collection of rules to 
+identify capabilities in a program. You can run capa against a PE file, ELF file, or shellcode and it tells you what it thinks the program can do. For example, it might suggest that 
+the program is a backdoor, can install services, or relies on HTTP to communicate. capa explorer runs capa analysis on your IDA Pro database (IDB) without needing access
+to the original binary file. Once a database has been analyzed, capa explorer helps you identify interesting areas of a program and build new capa rules using features extracted from your IDB.
+
+We love using capa explorer during malware analysis because it teaches us what parts of a program suggest a behavior. As we click on rows, capa explorer jumps directly 
+to important addresses in the IDB and highlights key features in the Disassembly view so they stand out visually. To illustrate, we use capa explorer to 
+analyze Lab 14-02 from [Practical Malware Analysis](https://nostarch.com/malware) (PMA) available [here](https://practicalmalwareanalysis.com/labs/). Our goal is to understand 
+the program's functionality.
+
+After loading Lab 14-02 into IDA and analyzing the database with capa explorer, we see that capa detected a rule match for `self delete via COMSPEC environment variable`:
+
+![](../../../doc/img/explorer_condensed.png)
+
+We can use capa explorer to navigate our Disassembly view directly to the suspect function and get an assembly-level breakdown of why capa matched `self delete via COMSPEC environment variable`.
+
+![](../../../doc/img/explorer_expanded.png)
+
+Using the `Rule Information` and `Details` columns capa explorer shows us that the suspect function matched `self delete via COMSPEC environment variable` because it contains capa rule matches for `create process`, `get COMSPEC environment variable`,
+and `query environment variable`, references to the strings `COMSPEC`, ` > nul`, and `/c del `, and calls to the Windows API functions `GetEnvironmentVariableA` and `ShellExecuteEx`.
+
+capa explorer also helps you build and test new capa rules. To start, select the `Rule Generator` tab, navigate to a function in your Disassembly view,
+and click `Analyze`. capa explorer will extract features from the function and display them in the `Features` pane. You can add features listed in this pane to the `Editor` pane
+by either double-clicking a feature or using multi-select + right-click to add multiple features at once. The `Preview` and `Editor` panes help edit your rule. Use the `Preview` pane
+to modify rule text directly and the `Editor` pane to construct and rearrange your hierarchy of statements and features. When you finish a rule you can save it directly to a file by clicking `Save`.
+
+![](../../../doc/img/rulegen_expanded.png)
+
+For more information on the FLARE team's open-source framework, capa, check out the overview in our first [blog](https://www.mandiant.com/resources/capa-automatically-identify-malware-capabilities).
+
+## Getting Started
+
+### Installation
+
+You can install capa explorer using the following steps:
+
+1. Install capa and its dependencies from PyPI using the Python interpreter configured for your IDA installation:
+    ```
+    $ pip install flare-capa
+    ```
+2. Download and extract the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match the version of capa you have installed
+   1. Use the following command to view the version of capa you have installed:
+   ```commandline
+    $ pip show flare-capa
+    OR
+    $ capa --version
+    ```
+3. Copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ida/plugin/capa_explorer.py) to your IDA plugins directory
+   - find your plugin directories via `idaapi.get_ida_subdirs("plugins")` or see this [Hex-Rays blog](https://hex-rays.com/blog/igors-tip-of-the-week-103-sharing-plugins-between-ida-installs/)
+   - common paths are `%APPDATA%\Hex-Rays\IDA Pro\plugins` (Windows) or `$HOME/.idapro/plugins` on Linux/Mac
+
+### Supported File Types
+
+capa explorer is limited to the file types supported by capa, which include:
+
+* Windows x86 (32- and 64-bit) PE files
+* Windows x86 (32- and 64-bit) shellcode
+* ELF files on various operating systems
+
+### Usage
+
+1. Open IDA and analyze a supported file type (select the `Manual Load` and `Load Resources` options in IDA for best results)
+2. Open capa explorer in IDA by navigating to `Edit > Plugins > FLARE capa explorer` or using the keyboard shortcut `Alt+F5`
+   You can also use `ida_loader.load_and_run_plugin("capa_explorer", arg)`. `arg` is a bitflag for which setting the LSB enables automatic analysis. See `capa.ida.plugin.form.Options` for more details.
+3. Select the `Program Analysis` tab
+4. Click the `Analyze` button
+
+The first time you run capa explorer you will be asked to specify a local directory containing capa rules to use for analysis. We recommend downloading and extracting the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match 
+the version of capa you have installed (see installation instructions above for more details). capa explorer remembers your selection for future analysis which you
+can update using the `Settings` button.
+
+#### Tips for Program Analysis
+
+* Start analysis by clicking the `Analyze` button
+  * capa explorer caches results to the database and reuses them across IDA sessions 
+* Reset the plugin user interface and remove highlighting from your Disassembly view by clicking the `Reset` button
+* Change your local capa rules directory, auto analysis settings, and other default settings by clicking the `Settings` button
+* Hover your cursor over a rule match to view the source content of the rule
+* Double-click the `Address` column to navigate your Disassembly view to the address of the associated feature
+* Double-click a result in the `Rule Information` column to expand its children
+* Select a checkbox in the `Rule Information` column to highlight the address of the associated feature in your Disassembly view
+
+#### Tips for Rule Generator
+
+* Navigate to a function in your Disassembly view and click`Analyze` to get started
+* Double-click or use multi-select + right-click to add features from the `Features` pane to the `Editor` pane
+* Right-click features in the `Editor` pane to make context-specific modifications
+* Drag-and-drop (single click + multi-select support) features in the `Editor` pane to construct your hierarchy of statements and features
+* Right-click anywhere in the `Editor` pane not on a feature to remove all features
+* Add descriptions or comments to a feature by editing the corresponding column in the `Editor` pane
+* Directly edit rule text and metadata fields using the `Preview` pane
+* Change the default rule author and default rule scope displayed in the `Preview` pane by clicking `Settings`
+
+### Requirements
+
+capa explorer supports Python versions >= 3.8.x and IDA Pro versions >= 7.4. The following IDA Pro versions have been tested:
+
+* IDA 7.4
+* IDA 7.5
+* IDA 7.6 Service Pack 1
+* IDA 7.7
+* IDA 8.0
+* IDA 8.1
+* IDA 8.2
+
+capa explorer is however limited to the Python versions supported by your IDA installation (which may not include all Python versions >= 3.8.x).
+
+If you encounter issues with your specific setup, please open a new [Issue](https://github.com/mandiant/capa/issues).
+
+## Development
+
+capa explorer is packaged with capa so you will need to install capa locally for development. You can install capa locally by following the steps outlined in `Method 3: Inspecting the capa source code` of the [capa 
+installation guide](https://github.com/mandiant/capa/blob/master/doc/installation.md#method-3-inspecting-the-capa-source-code). Once installed, copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ida/plugin/capa_explorer.py) 
+to your plugins directory to install capa explorer in IDA.
+
+### Components
+
+capa explorer consists of two main components:
+
+* An [feature extractor](https://github.com/mandiant/capa/tree/master/capa/features/extractors/ida) built on top of IDA's binary analysis engine
+  * This component uses IDAPython to extract [capa features](https://github.com/mandiant/capa-rules/blob/master/doc/format.md#extracted-features) from your IDBs such as strings, 
+disassembly, and control flow; these extracted features are used by capa to find feature combinations that result in a rule match
+* An [interactive user interface](https://github.com/mandiant/capa/tree/master/capa/ida/plugin) for displaying and exploring capa rule matches
+  * This component integrates the feature extractor and capa, providing an interactive user interface to dissect rule matches found by capa using features extracted directly from your IDBs

capa/ida/plugin/__init__.py

@@ -0,0 +1,139 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+import logging
+
+import idaapi
+import ida_kernwin
+
+from capa.ida.plugin.form import CapaExplorerForm
+from capa.ida.plugin.icon import ICON
+
+logger = logging.getLogger(__name__)
+
+
+class CapaExplorerPlugin(idaapi.plugin_t):
+    # Mandatory definitions
+    PLUGIN_NAME = "FLARE capa explorer"
+    PLUGIN_VERSION = "1.0.0"
+    PLUGIN_AUTHORS = "michael.hunhoff@mandiant.com, william.ballenthin@mandiant.com, moritz.raabe@mandiant.com"
+
+    wanted_name = PLUGIN_NAME
+    wanted_hotkey = "ALT-F5"
+    comment = "IDA Pro plugin for the FLARE team's capa tool to identify capabilities in executable files."
+    website = "https://github.com/mandiant/capa"
+    help = "See https://github.com/mandiant/capa/blob/master/doc/usage.md"
+    version = ""
+    flags = 0
+
+    def __init__(self):
+        """initialize plugin"""
+        self.form = None
+
+    def init(self):
+        """called when IDA is loading the plugin"""
+        logging.basicConfig(level=logging.INFO)
+
+        # do not load plugin unless hosted in idaq (IDA Qt)
+        if not idaapi.is_idaq():
+            # note: it does not appear that IDA calls "init" by default when hosted in idat; we keep this
+            # check here for good measure
+            return idaapi.PLUGIN_SKIP
+
+        import capa.ida.helpers
+
+        # do not load plugin if IDA version/file type not supported
+        if not capa.ida.helpers.is_supported_ida_version():
+            return idaapi.PLUGIN_SKIP
+        if not capa.ida.helpers.is_supported_file_type():
+            return idaapi.PLUGIN_SKIP
+        if not capa.ida.helpers.is_supported_arch_type():
+            return idaapi.PLUGIN_SKIP
+        return idaapi.PLUGIN_OK
+
+    def term(self):
+        """called when IDA is unloading the plugin"""
+        pass
+
+    def run(self, arg):
+        """
+        called when IDA is running the plugin as a script
+
+        args:
+          arg (int): bitflag. Setting LSB enables automatic analysis upon
+          loading. The other bits are currently undefined. See `form.Options`.
+        """
+        if not self.form:
+            self.form = CapaExplorerForm(self.PLUGIN_NAME, arg)
+        else:
+            widget = idaapi.find_widget(self.form.form_title)
+            if widget:
+                idaapi.activate_widget(widget, True)
+            else:
+                self.form.Show()
+                self.form.load_capa_results(False, True)
+
+        return True
+
+
+# set the capa plugin icon.
+#
+# TL;DR: temporarily install a UI hook set the icon.
+#
+# Long form:
+#
+# in the IDAPython `plugin_t` life cycle,
+#   - `init` decides if a plugin should be registered
+#   - `run` executes the main logic (shows the window)
+#   - `term` cleans this up
+#
+# we want to associate an icon with the plugin action - which is created by IDA.
+# however, this action is created by IDA *after* `init` is called.
+# so, we can't do this in `plugin_t.init`.
+# we also can't spawn a thread and do it after a delay,
+#  since `ida_kernwin.update_action_icon` must be called from the main thread.
+# so we need to register a callback that's invoked from the main thread after the plugin is registered.
+#
+# after a lot of guess-and-check, we can use `UI_Hooks.updated_actions` to
+#  receive notifications after IDA has created an action for each plugin.
+# so, create this hook, wait for capa plugin to load, set the icon, and unhook.
+
+
+class OnUpdatedActionsHook(ida_kernwin.UI_Hooks):
+    """register a callback to be invoked each time the UI actions are updated"""
+
+    def __init__(self, cb):
+        super().__init__()
+        self.cb = cb
+
+    def updated_actions(self):
+        if self.cb():
+            # uninstall the callback once its run successfully
+            self.unhook()
+
+
+def install_icon():
+    plugin_name = CapaExplorerPlugin.PLUGIN_NAME
+    action_name = "Edit/Plugins/" + plugin_name
+
+    if action_name not in ida_kernwin.get_registered_actions():
+        # keep the hook registered
+        return False
+
+    # resource leak here. need to call `ida_kernwin.free_custom_icon`?
+    # however, since we're not cycling this icon a lot, its probably ok.
+    # expect to leak exactly one icon per application load.
+    icon = ida_kernwin.load_custom_icon(data=ICON)
+
+    ida_kernwin.update_action_icon(action_name, icon)
+
+    # uninstall the hook
+    return True
+
+
+h = OnUpdatedActionsHook(install_icon)
+h.hook()

capa/ida/plugin/cache.py

@@ -0,0 +1,229 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from __future__ import annotations
+
+import itertools
+import collections
+from typing import Set, Dict, Tuple, Union, Optional
+
+import capa.engine
+from capa.rules import Scope, RuleSet
+from capa.engine import FeatureSet, MatchResults
+from capa.features.address import NO_ADDRESS, Address
+from capa.ida.plugin.extractor import CapaExplorerFeatureExtractor
+from capa.features.extractors.base_extractor import BBHandle, InsnHandle, FunctionHandle
+
+
+class CapaRuleGenFeatureCacheNode:
+    def __init__(
+        self,
+        inner: Optional[Union[FunctionHandle, BBHandle, InsnHandle]],
+        parent: Optional[CapaRuleGenFeatureCacheNode],
+    ):
+        self.inner: Optional[Union[FunctionHandle, BBHandle, InsnHandle]] = inner
+        self.address = NO_ADDRESS if self.inner is None else self.inner.address
+        self.parent: Optional[CapaRuleGenFeatureCacheNode] = parent
+
+        if self.parent is not None:
+            self.parent.children.add(self)
+
+        self.features: FeatureSet = collections.defaultdict(set)
+        self.children: Set[CapaRuleGenFeatureCacheNode] = set()
+
+    def __hash__(self):
+        # TODO(mike-hunhoff): confirm this is unique enough
+        # https://github.com/mandiant/capa/issues/1604
+        return hash((self.address,))
+
+    def __eq__(self, other):
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        # TODO(mike-hunhoff): confirm this is unique enough
+        # https://github.com/mandiant/capa/issues/1604
+        return self.address == other.address
+
+
+class CapaRuleGenFeatureCache:
+    def __init__(self, extractor: CapaExplorerFeatureExtractor):
+        self.extractor = extractor
+        self.global_features: FeatureSet = collections.defaultdict(set)
+
+        self.file_node: CapaRuleGenFeatureCacheNode = CapaRuleGenFeatureCacheNode(None, None)
+        self.func_nodes: Dict[Address, CapaRuleGenFeatureCacheNode] = {}
+        self.bb_nodes: Dict[Address, CapaRuleGenFeatureCacheNode] = {}
+        self.insn_nodes: Dict[Address, CapaRuleGenFeatureCacheNode] = {}
+
+        self._find_global_features()
+        self._find_file_features()
+
+    def _find_global_features(self):
+        for feature, addr in self.extractor.extract_global_features():
+            # not all global features may have virtual addresses.
+            # if not, then at least ensure the feature shows up in the index.
+            # the set of addresses will still be empty.
+            if addr is not None:
+                self.global_features[feature].add(addr)
+            else:
+                if feature not in self.global_features:
+                    self.global_features[feature] = set()
+
+    def _find_file_features(self):
+        # not all file features may have virtual addresses.
+        # if not, then at least ensure the feature shows up in the index.
+        # the set of addresses will still be empty.
+        for feature, addr in self.extractor.extract_file_features():
+            if addr is not None:
+                self.file_node.features[feature].add(addr)
+            else:
+                if feature not in self.file_node.features:
+                    self.file_node.features[feature] = set()
+
+    def _find_function_and_below_features(self, fh: FunctionHandle):
+        f_node: CapaRuleGenFeatureCacheNode = CapaRuleGenFeatureCacheNode(fh, self.file_node)
+
+        # extract basic block and below features
+        for bbh in self.extractor.get_basic_blocks(fh):
+            bb_node: CapaRuleGenFeatureCacheNode = CapaRuleGenFeatureCacheNode(bbh, f_node)
+
+            # extract instruction features
+            for ih in self.extractor.get_instructions(fh, bbh):
+                inode: CapaRuleGenFeatureCacheNode = CapaRuleGenFeatureCacheNode(ih, bb_node)
+
+                for feature, addr in self.extractor.extract_insn_features(fh, bbh, ih):
+                    inode.features[feature].add(addr)
+
+                self.insn_nodes[inode.address] = inode
+
+            # extract basic block features
+            for feature, addr in self.extractor.extract_basic_block_features(fh, bbh):
+                bb_node.features[feature].add(addr)
+
+            # store basic block features in cache and function parent
+            self.bb_nodes[bb_node.address] = bb_node
+
+        # extract function features
+        for feature, addr in self.extractor.extract_function_features(fh):
+            f_node.features[feature].add(addr)
+
+        self.func_nodes[f_node.address] = f_node
+
+    def _find_instruction_capabilities(
+        self, ruleset: RuleSet, insn: CapaRuleGenFeatureCacheNode
+    ) -> Tuple[FeatureSet, MatchResults]:
+        features: FeatureSet = collections.defaultdict(set)
+
+        for feature, locs in itertools.chain(insn.features.items(), self.global_features.items()):
+            features[feature].update(locs)
+
+        _, matches = ruleset.match(Scope.INSTRUCTION, features, insn.address)
+        for name, result in matches.items():
+            rule = ruleset[name]
+            for addr, _ in result:
+                capa.engine.index_rule_matches(features, rule, [addr])
+
+        return features, matches
+
+    def _find_basic_block_capabilities(
+        self, ruleset: RuleSet, bb: CapaRuleGenFeatureCacheNode
+    ) -> Tuple[FeatureSet, MatchResults, MatchResults]:
+        features: FeatureSet = collections.defaultdict(set)
+        insn_matches: MatchResults = collections.defaultdict(list)
+
+        for insn in bb.children:
+            ifeatures, imatches = self._find_instruction_capabilities(ruleset, insn)
+            for feature, locs in ifeatures.items():
+                features[feature].update(locs)
+            for name, result in imatches.items():
+                insn_matches[name].extend(result)
+
+        for feature, locs in itertools.chain(bb.features.items(), self.global_features.items()):
+            features[feature].update(locs)
+
+        _, matches = ruleset.match(Scope.BASIC_BLOCK, features, bb.address)
+        for name, result in matches.items():
+            rule = ruleset[name]
+            for loc, _ in result:
+                capa.engine.index_rule_matches(features, rule, [loc])
+
+        return features, matches, insn_matches
+
+    def find_code_capabilities(
+        self, ruleset: RuleSet, fh: FunctionHandle
+    ) -> Tuple[FeatureSet, MatchResults, MatchResults, MatchResults]:
+        f_node: Optional[CapaRuleGenFeatureCacheNode] = self._get_cached_func_node(fh)
+        if f_node is None:
+            return {}, {}, {}, {}
+
+        insn_matches: MatchResults = collections.defaultdict(list)
+        bb_matches: MatchResults = collections.defaultdict(list)
+        function_features: FeatureSet = collections.defaultdict(set)
+
+        for bb in f_node.children:
+            features, bmatches, imatches = self._find_basic_block_capabilities(ruleset, bb)
+            for feature, locs in features.items():
+                function_features[feature].update(locs)
+            for name, result in bmatches.items():
+                bb_matches[name].extend(result)
+            for name, result in imatches.items():
+                insn_matches[name].extend(result)
+
+        for feature, locs in itertools.chain(f_node.features.items(), self.global_features.items()):
+            function_features[feature].update(locs)
+
+        _, function_matches = ruleset.match(Scope.FUNCTION, function_features, f_node.address)
+        return function_features, function_matches, bb_matches, insn_matches
+
+    def find_file_capabilities(self, ruleset: RuleSet) -> Tuple[FeatureSet, MatchResults]:
+        features: FeatureSet = collections.defaultdict(set)
+
+        for func_node in self.file_node.children:
+            assert func_node.inner is not None
+            assert isinstance(func_node.inner, FunctionHandle)
+
+            func_features, _, _, _ = self.find_code_capabilities(ruleset, func_node.inner)
+            for feature, locs in func_features.items():
+                features[feature].update(locs)
+
+        for feature, locs in itertools.chain(self.file_node.features.items(), self.global_features.items()):
+            features[feature].update(locs)
+
+        _, matches = ruleset.match(Scope.FILE, features, NO_ADDRESS)
+        return features, matches
+
+    def _get_cached_func_node(self, fh: FunctionHandle) -> Optional[CapaRuleGenFeatureCacheNode]:
+        f_node: Optional[CapaRuleGenFeatureCacheNode] = self.func_nodes.get(fh.address)
+        if f_node is None:
+            # function is not in our cache, do extraction now
+            self._find_function_and_below_features(fh)
+            f_node = self.func_nodes.get(fh.address)
+        return f_node
+
+    def get_all_function_features(self, fh: FunctionHandle) -> FeatureSet:
+        f_node: Optional[CapaRuleGenFeatureCacheNode] = self._get_cached_func_node(fh)
+        if f_node is None:
+            return {}
+
+        all_function_features: FeatureSet = collections.defaultdict(set)
+        all_function_features.update(f_node.features)
+
+        for bb_node in f_node.children:
+            for i_node in bb_node.children:
+                for feature, locs in i_node.features.items():
+                    all_function_features[feature].update(locs)
+            for feature, locs in bb_node.features.items():
+                all_function_features[feature].update(locs)
+
+        # include global features just once
+        for feature, locs in self.global_features.items():
+            all_function_features[feature].update(locs)
+
+        return all_function_features
+
+    def get_all_file_features(self):
+        yield from itertools.chain(self.file_node.features.items(), self.global_features.items())

capa/ida/plugin/capa_explorer.py

@@ -0,0 +1,17 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+from capa.ida.plugin import CapaExplorerPlugin
+
+
+def PLUGIN_ENTRY():
+    """mandatory entry point for IDAPython plugins
+
+    copy this script to your IDA plugins directory and start the plugin by navigating to Edit > Plugins in IDA Pro
+    """
+    return CapaExplorerPlugin()

capa/ida/plugin/error.py

@@ -0,0 +1,13 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+
+class UserCancelledError(Exception):
+    """throw exception when user cancels action"""
+
+    pass

capa/ida/plugin/extractor.py

@@ -0,0 +1,44 @@
+# Copyright (C) 2023 Mandiant, Inc. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at: [package root]/LICENSE.txt
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+
+import ida_kernwin
+from PyQt5 import QtCore
+
+from capa.ida.plugin.error import UserCancelledError
+from capa.features.extractors.ida.extractor import IdaFeatureExtractor
+from capa.features.extractors.base_extractor import FunctionHandle
+
+
+class CapaExplorerProgressIndicator(QtCore.QObject):
+    """implement progress signal, used during feature extraction"""
+
+    progress = QtCore.pyqtSignal(str)
+
+    def update(self, text):
+        """emit progress update
+
+        check if user cancelled action, raise exception for parent function to catch
+        """
+        if ida_kernwin.user_cancelled():
+            raise UserCancelledError("user cancelled")
+        self.progress.emit(f"extracting features from {text}")
+
+
+class CapaExplorerFeatureExtractor(IdaFeatureExtractor):
+    """subclass the IdaFeatureExtractor
+
+    track progress during feature extraction, also allow user to cancel feature extraction
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.indicator = CapaExplorerProgressIndicator()
+
+    def extract_function_features(self, fh: FunctionHandle):
+        self.indicator.update(f"function at {hex(fh.inner.start_ea)}")
+        return super().extract_function_features(fh)