diff --git a/README.md b/README.md index 7385833c34..f2ecc813db 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,68 @@ # TRAM -[![codecov](https://codecov.io/gh/center-for-threat-informed-defense/tram/branch/master/graph/badge.svg?token=YISO1NSAMZ)](https://codecov.io/gh/center-for-threat-informed-defense/tram) +[![MITRE ATT&CK® v13](https://img.shields.io/badge/MITRE%20ATT%26CK®-v13-red)](https://attack.mitre.org/versions/v13/) +![Build](https://img.shields.io/github/actions/workflow/status/center-for-threat-informed-defense/tram/test.yml) +[![Coverage](https://img.shields.io/codecov/c/github/center-for-threat-informed-defense/tram?token=ejCIZhBRGr)](https://codecov.io/gh/center-for-threat-informed-defense/tram) + +Threat Report ATT&CK Mapper (TRAM) is an open-source platform designed to to reduce cost +and increase the effectiveness of integrating ATT&CK across the CTI community. It does +this by automating the mapping of cyber threat intelligence (CTI) reports to MITRE +ATT&CK®. Threat intel providers, threat intel platforms, and analysts can use TRAM to +integrate ATT&CK more easily and consistently into their products. + +The platform works out of the box to identify up to 50 common ATT&CK techniques in text +documents; it also supports tailoring the model by annotating additional items and +rebuilding the model. This Wiki describes the results of the Center for Threat-Informed +Defense (CTID) research into automated ATT&CK mapping and provides details and +instructions for tailoring the platform to your organization's unique dataset. + +**Table Of Contents:** + +- [Getting Started](#getting-started) +- [Getting Involved](#getting-involved) +- [Questions and Feedback](#questions-and-feedback) +- [How do I contribute?](#how-do-i-contribute) +- [Notice](#notice) -Threat Report ATT&CK Mapping (TRAM) is an open-source platform designed to -advance research into automating the mapping of cyber threat intelligence -reports to MITRE ATT&CK®. +## Getting Started -TRAM enables researchers to test and refine Machine Learning (ML) models for -identifying ATT&CK techniques in prose-based cyber threat intel reports and -allows threat intel analysts to train ML models and validate ML results. +The TRAM web application can be deployed in a containerized environment with Docker or +Kubernetes. You should read the installation instructions to make sure that you are +comfortable with the prerequisites. Alternatively, if you want to focus on Machine +Learning Engineering, you can run the project notebooks for fine tuning your own models. -Through research into automating the mapping of cyber threat intel reports to -ATT&CK, TRAM aims to reduce the cost and increase the effectiveness of -integrating ATT&CK into cyber threat intelligence across the community. Threat -intel providers, threat intel platforms, and analysts should be able to use TRAM -to integrate ATT&CK more easily and consistently into their products. +| Resource | Description | +| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [Installation]((https://github.com/center-for-threat-informed-defense/tram/wiki/Installation)) | Instructions for downloading and installing TRAM container images | +| [Documentation](https://github.com/center-for-threat-informed-defense/tram/wiki) | Complete documentation for TRAM | +| [Notebooks](https://github.com/center-for-threat-informed-defense/tram/tree/main/user_notebooks) | Jupyter notebooks for SciBERT-based single-label and multi-label models. | +| [Developer Setup](https://github.com/center-for-threat-informed-defense/tram/wiki#for-developers) | Instructions for contributing code changes to TRAM. Only required for local development and testing. | -## Getting Started +## Getting Involved + +There are several ways that you can get involved with this project and help advance +threat-informed defense: -TRAM has integrated Machine Learning models into a Web UI and as part of Jupyter notebooks. - -* Follow the [installation](URL) instructions in the Wiki to pull the container images. If you’ve used TRAM before, you’re familiar with launching into the webUI and uploading a JSON, docx, pdf, or even txt report to for automatic analysis. +- **Install the TRAM web application and try processing CTI reports.** We welcome your + feedback on the effectiveness of using machine learning to identify TTPs in + human-readable text. +- **Share your use cases.** We are interested in developing additional tools and + resources to help the community understand and make threat-informed decisions in their + risk management programs. If you have ideas or suggestions, we consider them as we + explore additional research projects. +- **Label your own data and use the notebooks to fine tune your own models.** This is a + complex undertaking, but it allows you to adapt TRAM to your own environment and data. + If you have high end GPUs in your environment, you can run these notebooks on your own + instrastructure; otherwise you can run them on the paid or free tiers of [Google + Colab](https://colab.research.google.com/). -* Jupyter Notebooks can be found in [user_notebooks](https://github.com/center-for-threat-informed-defense/tram/tree/main/user_notebooks) for the SciBERT-based single-label model and multi-label model. There are supplemental notebooks tailored to further fine-tune each model with additional data. Links found in that section will also open the notebooks in [Google Colab](https://colab.research.google.com), an online service that enables GPU-focused workloads. +## Questions and Feedback -Resource | Description - -- | -- - [Installation Instructions]((https://github.com/center-for-threat-informed-defense/tram/wiki#installation)) | Instructions for downloading and installing TRAM container images - [Developer Setup](https://github.com/center-for-threat-informed-defense/tram/wiki#for-developers) | Instructions for developing TRAM. Only required for local development and testing. The containerized version is recommended for non-developers. - [Jupyter Notebooks](https://github.com/center-for-threat-informed-defense/tram/tree/main/user_notebooks) | SciBERT-based single-label model and multi-label model notebooks. Notebooks for further fine-tuning both single and multi-label models. - [Documentation](https://github.com/center-for-threat-informed-defense/tram/wiki) | Complete documentation for TRAM +Please submit issues for any technical questions/concerns or contact +ctid@mitre-engenuity.org directly for more general inquiries. + +Also see the guidance for contributors if are you interested in contributing or simply +reporting issues. ## How do I contribute? @@ -37,28 +70,17 @@ We welcome your feedback and contributions to help advance TRAM. Please see the guidance for contributors if are you interested in [contributing or simply reporting issues.](/CONTRIBUTING.md) +To contribute training data, see [the Data Annotation wiki](https://github.com/center-for-threat-informed-defense/tram-private/wiki/Data-Annotation). + Please submit [issues](https://github.com/center-for-threat-informed-defense/tram/issues) for any technical questions/concerns or contact ctid@mitre-engenuity.org directly for more general inquiries. -### Contribute Training Data - -All training data is formatted as a report export. If you are contributing -training data, please ensure that you have the right to publicly share the -threat report. Do not contribute reports that are proprietary material of -others. - -To contribute training data, please: - -1. Use TRAM to perform the mapping, and ensure that all mappings are accepted -2. Use the report export feature to export the report as JSON -3. Open a pull request where the training data is added to data/training/contrib - ## Notice -Copyright 2023 MITRE Engenuity. Approved for public release. Document number -TBD. +Copyright 2021, 2023 MITRE Engenuity. Approved for public release. Document number +CT0035. 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 diff --git a/docker/README.md b/docker/README.md index 767b3d7317..cd67a60116 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,60 +1,3 @@ # TRAM Docker Images -## Overview - -See the [main README](../README.md) for an overview of installing TRAM via -Docker. This document contains some additional detail that may be useful for -customizing your TRAM instance. - -## Environment Variables - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableRequired - Description
ALLOWED_HOSTSYes - A list of hostnames that TRAM can be served from.
DJANGO_SUPERUSER_USERNAMEYes - The username for the TRAM super user (the default account you sign in with).
DJANGO_SUPERUSER_PASSWORDYes - The password for the TRAM super user.
DJANGO_SUPERUSER_EMAILYes - The email address for the TRAM super user. (Not used in pratice, doesn't need to be a real address.)
DATA_DIRECTORYNo - Any ML data and DB data is stored at the path indicated at this environment variable. Defaults to ./data.
SECRET_KEYNo - - A cryptographic secret used by Django. This secret can be generated using this command: - $ python3 -c "import secrets; print(secrets.token_urlsafe())" - If not provided, then a random secret is created at startup. -
DEBUGNo - Set to `true` or `yes` to enable Django debug mode, otherwise debug mode is disabled.
+See the [installation wiki](/center-for-threat-informed-defense/tram/wiki/Installation#web-application) for instructions about TRAM's Docker images. diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 1bc6ebeb6c..7365c4c526 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -9,7 +9,7 @@ version: '3.5' services: tram: - image: ghcr.io/center-for-threat-informed-defense/tram-private:swfarnsworth-bert-django-container-buildable + image: docker.io/library/tram:dev environment: - DATA_DIRECTORY=/tram/data - ALLOWED_HOSTS=["example_host1", "localhost"] @@ -20,7 +20,7 @@ services: - tram:/tram/data - tram_static:/tram/src/tram/staticfiles nginx: - image: ghcr.io/center-for-threat-informed-defense/tram-private-nginx:swfarnsworth-bert-django-container-buildable + image: docker.io/library/tram-nginx:dev ports: - "8000:80" volumes: diff --git a/pyproject.toml b/pyproject.toml index 5e37fe2754..e47a10891d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,14 +1,11 @@ [build-system] -requires = [ - "setuptools>=61", - "wheel" -] +requires = ["setuptools>=61", "wheel"] build-backend = "setuptools.build_meta" [project] name = "tram" version = "1.3.0" -description = "Threat Report ATT&CK Mapping (TRAM) is an open-source platform designed to advance research into automating the mapping of cyber threat intelligence reports to MITRE ATT&CK®." +description = "Threat Report ATT&CK Mapper (TRAM) is an open-source platform designed to advance research into automating the mapping of cyber threat intelligence reports to MITRE ATT&CK®." readme = "README.md" requires-python = ">=3.8"