How to Contribute

Introduction

Unprotect is a collaborative platform dedicated to uncovering and documenting malware evasion techniques. As these techniques constantly evolve, maintaining an exhaustive list is nearly impossible at least, not without your valuable contributions.

We invite you to join us in this exciting journey and add your expertise to our collective efforts. By contributing, you'll help strengthen the project and push the boundaries of what we can achieve together.

To get started, please take a moment to read through this guide. It explains how to contribute effectively and ensures your input aligns with our goals.

Thank you for your interest, and we look forward to welcoming you as a contributor to the Unprotect project. Let's build something great together!

How To

To ensure convenience and better tracking of contributions, we have opted to use a dedicated GitHub repository. Simply fork the repository, make your contribution(s), and submit a pull request. Our team will review your submission and merge it if it aligns with the project's goals and standards. Before submitting your pull request, please carefully review the contribution rules and guidelines.

Contribution Rules

• Avoid Duplication: Before proposing a new evasion technique, ensure it is not already covered by an existing technique. Double-check the repository / web platform for any similar submissions.
• Include External Resources: If your evasion technique relies on external resources and research (e.g., podcast, video, blog or papers), make sure to include them in the submission template.
• Credit Original Authors
  • Respect the paternity of code snippets and detection rules. Always credit the original author(s).
  • By default, we will credit you as the author of the evasion technique. Therefore, exercise caution when submitting code snippets or rules derived from external sources.
  • If the code snippet originates from a private source, ensure you have obtained proper authorization before submission. Attribution to the original author remains mandatory.
• Prohibited Actions
  • Copying and pasting code from external sources without appropriate credit is strictly forbidden.
  • Submitting code or techniques without proper credit or authorization may result in a ban from our contributor program.
• Reporting Misattribution
  • If you find a code snippet or rule that belongs to you but was submitted without your permission or proper credit, notify us immediately.
  • We will investigate and either attribute the snippet to you or remove it from the repository.
• Adding Related Rules
  • It is highly encouraged to include related YARA, CAPA, or Sigma rules with your proposed technique.
  • If you authored the rule, add your name to the metadata. If the rule was created by someone else, maintain the original authorship.
• Code and Rule Validation
  • All code snippets and detection rules must be tested and verified as functional before submission.
  • If a code snippet relies on external libraries, tools, or resources, include this information in the code snippet's description to ensure proper evaluation and reproducibility.
• Modifying Existing Techniques or Rules
  • To modify an existing technique, code snippet, or rule, locate it in the GitHub repository. Update the relevant files and submit a pull request with your proposed changes.
  • If the technique or rule is not currently in the repository, you may create a new entry for your proposal.
• Submission Templates: Use the provided templates for all submissions. Adhering to the templates helps streamline the review and merge process.

Templates

Propose New Technique

Before submitting a new evasion technique, use the search box below to check if it is already covered or partially documented in our database. This ensures that duplicate or redundant entries are avoided and maintains the integrity of our collection:

Existing Categories

Sandbox Evasion

Antivirus/EDR Evasion

Anti-Debugging

Process Manipulating

Anti-Disassembly

Anti-Monitoring

Data Obfuscation

Anti-Forensic

Network Evasion

Defense Evasion [Mitre]

Packers

Others

To contribute a new technique, navigate to the Techniques directory at the root of the repository, where every entry is organized within its own dedicated folder. You can propose a new addition by creating a directory named after the technique itself, just be sure to sanitize the name to ensure it reflects the technique accurately while avoiding any forbidden path characters.

inside your newly created snippet folder, structure your files as follows:

File: info.yaml

info.yaml file is populated with the necessary metadata; you can find a guide on how to format and fill this file in the template provided below:

# Template

name: "[Name of the technique or concept]"
categories:
    - "[Category 1]"
    - "[Category 2]"
    - ...
featured_apis:
    - "[API 1]"
    - "[API 2]"
    - ...
resources:
    - "[Link to a relevant article, paper, or resource]"
    - "[Link to a relevant article, paper, or resource]"
    - ...
tags:
    - "[Tag 1]"
    - "[Tag 2]"
    - ...
contributors:
    - "[Your Name or Alias]"
    - "[Other Contributor Name or Alias]"
    - ...

# Example

name: "Indirect Memory Writing"
categories:
    - "Antivirus/EDR Evasion"
    - "Data Obfuscation"
resources:
    - "https://github.com/mimorep/Indirect-Shellcode-Executor"
    - "https://github.com/chmod760/CopyReadProcessMemory"
tags:
    - "AMSI Bypass"
contributors:
    - "DarkCoderSc"

Field Instructions

Here is a breakdown of what belongs in each field:

• name: A short, descriptive title for the entry. Keep it concise but specific.
• categories: The high-level classifications for this entry. Please use the exact names from the list above to ensure proper indexing (e.g., "Sandbox Evasion", "Anti-Debugging", "Anti-Forensics").
• resources: A list of URLs pointing to relevant GitHub repositories, articles, whitepapers, or documentation that explain or demonstrate the concept.
• tags: Granular keywords that help users search for and filter this specific entry.
• contributors: Handles or aliases for yourself and any original authors. This ensures everyone receives proper attribution for their work.

File: description.txt

To complete the contribution requirements for the technique's directory, you must also include a description.txt file. This plain text file serves as the primary source for the detailed explanation of the technique, its inner workings, and any necessary context. Because this content is rendered directly on the technique's public page, it should be as clear, professional, and informative as possible.

The file fully supports Markdown formatting, enabling you to use headers, lists, and links to improve the overall structure and readability. While you are encouraged to include code snippets to illustrate the logic, please keep them concise and focused on the specific mechanism being described; avoid dumping large, unorganized blocks of code. For extensive examples or multi-file implementations, please utilize our dedicated snippet contribution process instead of including them in the main description.

To ensure your contribution is valid and maximize its chances of acceptance, both the info.yaml and description.txt files must be present and strictly adhere to the required formats. Please note that submissions missing these core files or failing to respect the specified structure will be rejected. Adhering to these guidelines is essential for maintaining the quality of the repository and ensures a much smoother, faster review process for your submission.

Propose New Code Snippet

Each evasion technique can be illustrated with one or more working code snippets across various programming languages. You can even provide alternative implementations in a language that already has existing examples.

Before proposing a new code snippet, please review the existing submissions for that specific technique. Ensure that an identical or highly similar snippet in your chosen programming language does not already exist. If your approach is unique or offers a significantly different method, you are welcome to proceed!

Navigate to the target technique's root directory. If it does not already exist, create a new sub-directory called Snippets.

Inside this Snippets directory, create a dedicated folder for your code using the following strict naming convention:

[ProgrammingLanguage]_[AuthorName]

Handling Multiple Submissions: If you (the same author) are submitting multiple distinct snippets for the same technique in the same programming language, append an incremental number to the end of the folder name:

• First snippet: Delphi_DarkCoderSc
• Second snippet: Delphi_DarkCoderSc_2

File: info.yaml

info.yaml file is populated with the necessary metadata; you can find a guide on how to format and fill this file in the template provided below:

# Template

language: "[Programming language of the snippet]"
contributors:
  - "[Your Name or Alias]"
  - "[Other Contributor Name or Alias - if any]"
associated_technique: "[Exact name of the technique this snippet demonstrates]"
target_operating_system: "[windows, linux or macos]"

# Example

language: "Delphi"
contributors: "DarkCoderSc"
associated_technique: "Indirect Memory Writing"
target_operating_system: "windows"

File: code.txt

The code.txt file contains the actual code snippet that demonstrates the evasion technique. This file should be a plain text file with the code properly formatted and organized for readability. It is crucial to ensure that the code is functional and tested before submission.

(Optional) File: description.txt

If required, you can create a description.txt file to provide a detailed explanation of the code snippet, its logic, and any necessary context. This file is optional but highly recommended, especially for more complex snippets. Like the main technique description, this file also supports Markdown formatting, allowing you to structure the content with headers, lists, and links for improved readability.

To ensure your contribution is valid and maximize its chances of acceptance, both the info.yaml and code.txt files must be present and strictly adhere to the required formats. Please note that submissions missing these core files or failing to respect the specified structure will be rejected. Adhering to these guidelines is essential for maintaining the quality of the repository and ensures a much smoother, faster review process for your submission.

Special Note

If your implementation is more extensive such as a complete project consisting of multiple files, third-party library dependencies, or complex environment configurations please do not submit it as a standard code snippet. Instead, host the code in a dedicated GitHub repository. Once your repository is live, update the resources section of the corresponding technique's info.yaml file to include the link. This ensures the core database remains lightweight while still providing users with a direct path to your full implementation.

Propose New Detection Rule

Each evasion technique can be identified using one or more detection rules. We currently support rules in various formats, including YARA, CAPA, and SIGMA. You can propose a new rule or provide an alternative detection method to an existing one.

Before proposing a new detection rule, please review the existing submissions for that specific technique. Ensure that an identical or highly similar rule does not already exist. If your approach covers different indicators or offers a more robust detection method, you are welcome to proceed!

Navigate to the repository's root directory and locate the Rules directory.

Inside this Rules directory, create a dedicated folder for the target technique. The folder name should reflect the technique it detects, but it does not need to be an exact match (this is useful for omitting forbidden path characters like slashes or colons).

Then, inside your newly created rule folder, structure your files as follows:

File: info.yaml

The info.yaml file is populated with the necessary metadata. This is where you will define the exact, official name of the rule and its format.

# Template

name: "[Exact name of the detection rule]"
type: "[YARA, CAPA, or SIGMA]"

# Example

name: "Detect ASProtect Packer"
type: "YARA"

File: rule.txt

The rule.txt file contains the actual raw text of the detection rule in plain text format.

For attribution, please use the native authorship fields inherent to the rule's format such as the author metadata field in a YARA rule to credit yourself as the creator.

To ensure your contribution is valid and maximize its chances of acceptance, both the info.yaml and rule.txt files must be present and strictly adhere to the required formats. Please note that submissions missing these core files, containing invalid rule syntax, or failing to respect the specified structure will be rejected. Adhering to these guidelines is essential for maintaining the quality of the repository and ensures a much smoother, faster review process for your submission.

Updating or Refining Existing Content

The repository is a living database, and we encourage contributors to refine existing techniques, code snippets, or detection rules. Whether you are correcting a technical inaccuracy, improving a description's clarity, or simply fixing a typo, your input helps maintain the high quality of the project.

You can propose changes to any existing entry by modifying the relevant files directly within the Techniques, Snippets, or Rules directories. However, when it comes to authorship credit in the info.yaml file, we ask that you follow these guidelines based on the nature of your contribution:

Attribution Guidelines

• Minor Improvements: If you are fixing typos, adjusting grammar, or making small formatting tweaks, please do not add your name to the info.yaml list. Being merged into the repository already lists you as a contributor in the GitHub repository history, which is sufficient for minor housekeeping.
• Substantial Modifications: If you provide heavy modifications, significant technical clarifications, or add substantial new sections to a technique or rule, you should add your name or alias to the contributors list. This ensures you receive proper credit for the intellectual effort and research contributed to the entry.

By maintaining this distinction, we ensure that the contributor metadata remains a meaningful reflection of the primary authors and major editors while still acknowledging the community effort involved in keeping the repository polished.

Missing Contribution Assignment

Until November 2024, user contributions to Detection Rule and Technique content additions or extensions were not programmatically accounted for. If you believe your contributions were missed, please reach on @DarkCoderSc, @Fr0gger_, or email. We will ensure your past contributions are properly acknowledged and recorded in the relevant fields.