Merge next into main

.github/workflows/ci.yml

@@ -72,6 +72,8 @@ jobs:
 
       - name: Run regression tests with code coverage
         run: npm run coverage:cobertura
+        env:
+          MONGOSTORE_CRYPTO_SECRET: 'ThisisASecretKeyForTestingPurposesOnly1234567890!@#$'
 
       - name: Upload Coverage to CodeCov
         uses: codecov/codecov-action@v4

.gitignore

@@ -1,3 +1,6 @@
+# A place to store artifacts during local development (scripts, datasets, dotenv files, etc.)
+.nocommit/**/*
+
 # Logs
 logs
 *.log

.releaserc

@@ -11,10 +11,6 @@
     {
       "name": "alpha",
       "prerelease": true
-    },
-    {
-      "name": "adm",
-      "prerelease": true
     }
   ],
   "plugins": [

.vscode/launch.json

@@ -11,7 +11,11 @@
       "skipFiles": ["<node_internals>/**"],
       "program": "${workspaceFolder}/bin/www",
       "outputCapture": "std",
-      "envFile": "${workspaceFolder}/.env"
+      "envFile": "${workspaceFolder}/.env",
+      "env": {
+        "DATABASE_URL": "mongodb://localhost:27017/attack-workspace",
+        "LOG_LEVEL": "debug"
+      }
     },
     {
       "type": "node",

CONTRIBUTING.md

@@ -60,20 +60,20 @@ If your changes are related to or dependent on changes in [attack-workbench-fron
 
 The project uses the following branch structure to support semantic-release:
 
-- `main` / `master`: Production-ready code
+- `main`: Production-ready code
 - `next`: Features for the next minor version
 - `next-major`: Features for the next major version
 - `beta`: Beta pre-releases
 - `alpha`: Alpha pre-releases
-- `*.*.x` or `*.x`: Maintenance branches for specific version releases
+- `*.x`: Maintenance branches for specific version releases
 
-Always target your pull requests to the `develop` branch unless specifically advised otherwise.
+Always target your pull requests to the `main` branch unless specifically advised otherwise.
 
 ## Commit Message Guidelines
 
 This project uses [conventional commits](https://www.conventionalcommits.org/) to automatically determine semantic versioning through semantic-release. Your commit messages should follow this format:
 
-```
+```text
 <type>(<scope>): <description>
 
 [optional body]
@@ -101,7 +101,7 @@ Adding `BREAKING CHANGE:` in the commit message footer will trigger a MAJOR vers
 The project uses GitHub Actions for continuous integration with the following workflow:
 
 1. **Commit Linting**: Ensures all commits follow the conventional commit format
-2. **Static Checks**: 
+2. **Static Checks**:
    - Runs linting checks
    - Performs security scanning with Snyk
    - Generates code coverage reports
@@ -140,11 +140,12 @@ Pre-release branches (alpha, beta) will generate pre-release versions with appro
 
 The project publishes Docker images to the GitHub Container Registry (ghcr.io) with these tags:
 
-- `latest`: Points to the most recent release from the main branch
-- `v{major}.{minor}.{patch}`: Specific version tags (e.g., `v1.2.3`)
-- `{major}.{minor}.{patch}`: Version tags without the 'v' prefix
-- `sha-{short-commit-sha}`: Specific commit reference
+- `latest`: Points to the most recent release from the `main` branch
+- `next`: Points to the most recent release from the `next` branch
+- `beta`: Points to the most recent release from the `beta` branch
+- `alpha`: Points to the most recent release from the `alpha` branch
+- `{major}.{minor}.{patch}`: Specific version tags (e.g., `v1.2.3`)
 
 Docker images include metadata such as version, build time, and commit reference, which are accessible via both environment variables and image labels.
 
-The image contains the Express.js REST API service and is designed to work with a MongoDB database.
+The image contains the Express.js REST API service and is designed to work with a MongoDB database.

README.md

@@ -33,7 +33,7 @@ For a full ATT&CK Workbench deployment, including the frontend application, see
 
 - [Usage Guide](USAGE.md): Comprehensive instructions for installing, configuring, and administering the REST API
 - [Contributing Guide](CONTRIBUTING.md): Information for developers about contributing to the project
-- [Data Model](docs/data-model.md): Technical details about the data models used in the application
+- [Data Model](docs/developer/data-model.md): Technical details about the data models used in the application
 
 ## Technical Information
 
@@ -57,10 +57,10 @@ Copyright 2020-2025 MITRE Engenuity. Approved for public release. Document numbe
 
 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
+<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.
 
 This project makes use of ATT&CK®
 
-[ATT&CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/)
+[ATT&CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/)

USAGE.md

@@ -18,9 +18,6 @@ This guide provides comprehensive instructions for installing, configuring, and
     - [Environment Variables](#environment-variables)
     - [Configuration File](#configuration-file)
   - [Authentication](#authentication)
-    - [Authentication Mechanisms](#authentication-mechanisms)
-    - [OpenID Connect (OIDC) Configuration](#openid-connect-oidc-configuration)
-    - [Service Authentication](#service-authentication)
   - [User Management](#user-management)
     - [User Roles and Permissions](#user-roles-and-permissions)
     - [User Account Status](#user-account-status)
@@ -37,6 +34,7 @@ This guide provides comprehensive instructions for installing, configuring, and
 The ATT&CK Workbench REST API provides services for storing, querying, and editing ATT&CK objects. It is built on Node.js and Express.js, and uses MongoDB for data persistence.
 
 This component is part of the larger ATT&CK Workbench application, which includes:
+
 - [ATT&CK Workbench Frontend](https://github.com/center-for-threat-informed-defense/attack-workbench-frontend)
 - [ATT&CK Workbench REST API](https://github.com/center-for-threat-informed-defense/attack-workbench-rest-api) (this component)
 
@@ -48,25 +46,29 @@ The recommended deployment method is using Docker. The REST API is published as
 
 #### Using Docker Compose (Recommended)
 
-The simplest way to deploy the entire ATT&CK Workbench application is using Docker Compose. Instructions are available in the [Workbench Deployment Guide](https://github.com/mitre-attack/attack-workbench-deployment).
+The simplest way to deploy the entire ATT&CK Workbench application is using Docker Compose.
+Instructions are available in the [Workbench Deployment Guide](https://github.com/mitre-attack/attack-workbench-deployment).
 
 #### Standalone Docker Deployment
 
 To run only the REST API in a Docker container:
 
 1. **Create a Docker network** (if not already created):
+
    ```shell
    docker network create attack-workbench-network
    ```
 
 2. **Run MongoDB container**:
+
    ```shell
    docker run --name attack-workbench-mongodb -d \
      --network attack-workbench-network \
      mongo:latest
    ```
 
 3. **Run REST API container**:
+
    ```shell
    docker run -p 3000:3000 -d \
      --name attack-workbench-rest-api \
@@ -86,6 +88,8 @@ docker run -p 3000:3000 -d \
   ghcr.io/center-for-threat-informed-defense/attack-workbench-rest-api:latest
 ```
 
+More infomation about configuration options is in the [configuration file documentation](./docs/admin/configuration.md).
+
 ### Manual Installation
 
 #### Requirements
@@ -96,19 +100,22 @@ docker run -p 3000:3000 -d \
 #### Installation Steps
 
 1. **Clone the repository**:
+
    ```shell
    git clone https://github.com/center-for-threat-informed-defense/attack-workbench-rest-api.git
    cd attack-workbench-rest-api
    ```
 
 2. **Install dependencies**:
+
    ```shell
    npm install
    ```
 
 3. **Configure the application** using environment variables or a configuration file (see [Configuration](#configuration)).
 
 4. **Start the application**:
+
    ```shell
    node ./bin/www
    ```
@@ -165,42 +172,8 @@ Example configuration file:
 
 ## Authentication
 
-The REST API supports different authentication mechanisms for both user and service authentication.
-
-### Authentication Mechanisms
-
-The application supports these user authentication mechanisms:
-
-- **Anonymous**: Default mechanism with no actual authentication (primarily for local development)
-- **OpenID Connect (OIDC)**: Integration with organizational identity providers
-
-### OpenID Connect (OIDC) Configuration
-
-To enable OIDC authentication:
-
-1. **Register with your OIDC Identity Provider** with these details:
-   - Authentication flow: Authorization Code Flow
-   - Required claims: `email` (required), `preferred_username` (optional), `name` (optional)
-   - Grant Types: Client Credentials, Authorization Code, and Refresh Token
-   - Redirect URL: `<host_url>/api/authn/oidc/callback`
-
-2. **Configure the REST API** with these environment variables:
-
-| Environment Variable | Required | Description | Configuration Property |
-|---------------------|----------|-------------|------------------------|
-| **AUTHN_MECHANISM** | Yes | Must be set to `oidc` | userAuthn.mechanism |
-| **AUTHN_OIDC_CLIENT_ID** | Yes | Client ID from your OIDC provider | userAuthn.oidc.clientId |
-| **AUTHN_OIDC_CLIENT_SECRET** | Yes | Client secret from your OIDC provider | userAuthn.oidc.clientSecret |
-| **AUTHN_OIDC_ISSUER_URL** | Yes | Issuer URL for the Identity Server | userAuthn.oidc.issuerUrl |
-| **AUTHN_OIDC_REDIRECT_ORIGIN** | Yes | URL for the Workbench host | userAuthn.oidc.redirectOrigin |
-
-### Service Authentication
-
-For service-to-service communication, the REST API supports three methods:
-
-1. **API Key Challenge Authentication**: Services obtain a JWT using a challenge-response protocol
-2. **API Key Basic Authentication**: Services authenticate using HTTP Basic Authentication
-3. **OIDC Client Credentials Flow**: Services obtain a JWT from an OIDC provider
+The REST API has several authentication options.
+Read all about them in the [authentication docs](./docs/admin/authentication/README.md).
 
 ## User Management
 
@@ -210,29 +183,29 @@ The REST API includes a user management system when using OIDC authentication.
 
 The system supports these roles:
 
-| Role | Description |
-|------|-------------|
-| `none` | No access to the system (for pending/inactive users) |
-| `visitor` | Read-only access to ATT&CK objects |
-| `editor` | Read and write access to ATT&CK objects |
-| `admin` | Full access to all system capabilities, including user management |
+| Role      | Description                                                       |
+|-----------|-------------------------------------------------------------------|
+| `none`    | No access to the system (for pending/inactive users)              |
+| `visitor` | Read-only access to ATT&CK objects                                |
+| `editor`  | Read and write access to ATT&CK objects                           |
+| `admin`   | Full access to all system capabilities, including user management |
 
 ### User Account Status
 
-| Status | Description |
-|--------|-------------|
-| `pending` | User has registered but awaits approval |
-| `active` | User is registered and approved |
-| `inactive` | User is no longer active |
+| Status     | Description                             |
+|------------|-----------------------------------------|
+| `pending`  | User has registered but awaits approval |
+| `active`   | User is registered and approved         |
+| `inactive` | User is no longer active                |
 
 ### User Management Endpoints
 
-| Endpoint | Method | Description | Authorization |
-|----------|--------|-------------|--------------|
-| `/api/user-accounts` | GET | List all users | Admin only |
-| `/api/user-accounts/:id` | GET | Get user by ID | Admin or self |
-| `/api/user-accounts/register` | POST | Register new user | Logged in, unregistered users |
-| `/api/user-accounts/:id` | PUT | Update user | Admin only |
+| Endpoint                      | Method | Description       | Authorization                 |
+|-------------------------------|--------|-------------------|-------------------------------|
+| `/api/user-accounts`          | GET    | List all users    | Admin only                    |
+| `/api/user-accounts/:id`      | GET    | Get user by ID    | Admin or self                 |
+| `/api/user-accounts/register` | POST   | Register new user | Logged in, unregistered users |
+| `/api/user-accounts/:id`      | PUT    | Update user       | Admin only                    |
 
 ## API Documentation
 
@@ -284,4 +257,4 @@ Common issues and their solutions:
 
 4. **Permission denied errors**:
    - Check the user's role and status
-   - Ensure the user account has the necessary permissions for the operation
+   - Ensure the user account has the necessary permissions for the operation

app/api/definitions/components/campaigns.yml

@@ -17,10 +17,6 @@ components:
         - type: object
           required:
             - name
-            - first_seen
-            - last_seen
-            - x_mitre_first_seen_citation
-            - x_mitre_last_seen_citation
           properties:
             # campaign specific properties
             name:

app/api/definitions/components/query-parameters.yml

@@ -0,0 +1,14 @@
+components:
+  parameters:
+    dryRun:
+      name: dryRun
+      in: query
+      description: |
+        When set to `true`, the request runs through the full composition and validation
+        pipeline but does not persist changes. Returns the composed object that would have
+        been created or updated.
+
+        Use this to validate data before committing it. Replaces the deprecated `POST /api/validate` endpoint.
+      schema:
+        type: boolean
+        default: false