Finishing touches to README

center-for-threat-informed-defense · Aug 27, 2023 · 0f8c6d7 · 0f8c6d7
1 parent 3a48cdc
commit 0f8c6d7
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 103 deletions.
diff --git a/README.md b/README.md
@@ -1,64 +1,86 @@
 # 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?
 
 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
@@ -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
-
-<table>
-  <thead>
-    <tr>
-      <th>Variable</th>
-      <th>Required<th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>ALLOWED_HOSTS</code></td>
-      <td>Yes<td>
-      <td>A list of hostnames that TRAM can be served from.</td>
-    </tr>
-    <tr>
-      <td><code>DJANGO_SUPERUSER_USERNAME</code></td>
-      <td>Yes<td>
-      <td>The username for the TRAM super user (the default account you sign in with).</td>
-    </tr>
-    <tr>
-      <td><code>DJANGO_SUPERUSER_PASSWORD</code></td>
-      <td>Yes<td>
-      <td>The password for the TRAM super user.</td>
-    </tr>
-    <tr>
-      <td><code>DJANGO_SUPERUSER_EMAIL</code></td>
-      <td>Yes<td>
-      <td>The email address for the TRAM super user. (Not used in pratice, doesn't need to be a real address.)</td>
-    </tr>
-    <tr>
-      <td><code>DATA_DIRECTORY</code></td>
-      <td>No<td>
-      <td>Any ML data and DB data is stored at the path indicated at this environment variable. Defaults to <code>./data</code>.</td>
-    </tr>
-    <tr>
-      <td><code>SECRET_KEY</code></td>
-      <td>No<td>
-      <td>
-        A cryptographic secret used by Django. This secret can be generated using this command:
-        <code>$ python3 -c "import secrets; print(secrets.token_urlsafe())"</code>
-        If not provided, then a random secret is created at startup.
-      </td>
-    </tr>
-    <tr>
-      <td><code>DEBUG</code></td>
-      <td>No<td>
-      <td>Set to `true` or `yes` to enable Django debug mode, otherwise debug mode is disabled.</td>
-    </tr>
-  </tbody>
-</table>
+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
@@ -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
@@ -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"