Contributing

Contributing

🙏 Thank you for taking the time to contribute! 💌 🙌

Ways to contribute

1. Find an issue and fix it
2. Contribute open-source intelligence information for an Adversary
3. (Coming soon) Add an adversary emulation plan

Find an issue and fix it 🎫

We use Github issues to track the following:

• Bug reports, including broken emulation procedures
• New feature requests
• Requests for updates or changes

You are welcome to comment on issues, open new issues, and open pull requests. View the list of current issues here.

Pull requests should target the develop branch of the repository.

Also, if you contribute any source code, we need you to agree to the following Developer's Certificate of Origin below.

Bug reports 🐞

Reporting issues with emulation procedures:

• Describe (in detail) what should have happened. Include any supporting information that may be helpful in resolving the issue.
• Be sure to include any steps to replicate the issue.
• Provide Caldera version (if applicable)
• Provide operating system information of the environment the emulation is executing inside

Developer's Certificate of Origin v1.1 🌱

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Contribute Open-source Intelligence for an Adversary

This is the first time we have opened this option up publicly. A little background...

Problem 💔

Adversary emulation is a specific style of offensive assessment that uses cyber threat intelligence to describe behaviors observed in specific campaigns or malware samples. The InfoSec community has expressed continued interest to support the Adversary Emulation Library through contributing open-source intelligence and analysis of available information. Due the nature of information sharing however, there is a balance between useful for emulation/detection and useful for adversaries to improve tooling. In other words, once you post something publicly, the adversary now knows you are aware of this behavior and can retool.

Solution ❤️‍🩹

We have deliberated on the best solution to include engage with the community while respecting information sharing boundaries and hope the community will support us and navigate these tricky waters with us.

Starting with the OceanLotus project we encourage community members to contribute open-source intelligence (OSINT) contributions using a new Issue template with an OceanLotus label. The OceanLotus project is currently under development and expected to end in August 2023. Please limit contributions to OceanLotus specifically while we test out this method.

Contribution Guidelines

We are testing this process specifically for OceanLotus, a macOS & Linux emulation plan.

Here is what we are looking for...

• macOS implant analysis
• Linux implant analysis (RotaJakiro - specifically information on shared object usage)
• Methods of lateral movement on these platforms

Helpful Information 🤩

• RE analysis (i.e. process injection, shared objects, methods of manipulating memory, etc.)
• Proof of concept code (i.e. code creating C2 communications packets based on cited OSINT)
• log files
• hands-on-keyboard commands (i.e. discovery commands)
• specific MITRE ATT&CK procedures (i.e. methods of lateral movement)
• unique technical patterns i.e. repeat behaviors in attacker life cycles across campaigns

Not as Helpful Information 😒

• A list of general articles found via a google search 🌐

Considerations

When sharing information please note all information shared on this repo is publicly available. By submitting an issue, you are certifying that you are allowed to share this information and grant all rights to its use to the Center for Threat-Informed Defense. For all source code contributions, ensure you agree with the Developer's Certificate of Origin.

Submit an OSINT Contribution

Use the below process to create an OSINT Contribution or click here to create a contribution issue directly

1. Navigate to the issue tab of the GitHub repo
2. Create a new issue
3. Click Get Started for the OSINT Contribution issue type
4. Add the OceanLotus label (right-hand side of the screen)
5. Add a title & fill out the form (🙏 with discernment)
6. Click Submit! 🥳

Only Contributions used in the emulation plan will receive contribution credit 📰

We will review and respond directly to your issue with comments, questions, and feedback. Any information we feel should not be shared we will remove from our repo. But we are a small team, so please think before submitting. 🤕

Our Goal in using this method…

• Provide the community a transparent feedback loop on our threat-driven approach
• Cultivate a community through encouraging and recognizing meaningful contributions accepted into an emulation plan
• Increase the available resources on technical analysis of these adversaries that empower red teams and detection engineers

Coming soon..... 🎥

• Open a pull request
• Designing Emulation plans
• Understanding our Repo
  • Directory Structure
  • Plug-ins
  • Testing

NOTE: We are actively working on different ways to contribute to our repo and what this process looks like. Please check back regularly here to see what's changed. Also, we would 😻 feedback on what we are doing well and what could be less painful 🧯.