From 112166829f1663b8368a92c35d222b4e0e169d85 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 07:31:07 +0000 Subject: [PATCH 1/3] Initial plan From deea3717ac09939ed7c4a944c7cc81c6a38a7b23 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 07:40:32 +0000 Subject: [PATCH 2/3] Add Swagger API documentation with UI renderer Co-authored-by: ruslanbaidan <3246171+ruslanbaidan@users.noreply.github.com> --- public/API_DOCUMENTATION.md | 98 ++ public/swagger-ui.html | 142 ++ public/swagger.yaml | 2531 ++++++++++++++++++++++++++++++++--- 3 files changed, 2604 insertions(+), 167 deletions(-) create mode 100644 public/API_DOCUMENTATION.md create mode 100644 public/swagger-ui.html diff --git a/public/API_DOCUMENTATION.md b/public/API_DOCUMENTATION.md new file mode 100644 index 0000000..d03d855 --- /dev/null +++ b/public/API_DOCUMENTATION.md @@ -0,0 +1,98 @@ +# MONARC API Documentation + +This directory contains the OpenAPI specification and Swagger UI for the MONARC API. + +## Files + +- `swagger.yaml` - OpenAPI 3.0.0 specification describing all MONARC API endpoints +- `swagger-ui.html` - Web interface for viewing and interacting with the API documentation + +## Accessing the API Documentation + +### Option 1: View in Browser (Recommended for local installations) + +If you have MONARC running locally, navigate to: +``` +http://your-monarc-installation/swagger-ui.html +``` + +### Option 2: Download and Use Swagger Editor + +1. Download the `swagger.yaml` file +2. Visit [Swagger Editor](https://editor.swagger.io/) +3. Import the `swagger.yaml` file + +### Option 3: Use with API Clients + +Import the `swagger.yaml` file into API testing tools: +- Postman +- Insomnia +- HTTPie +- Or any OpenAPI-compatible tool + +## Authentication + +Most API endpoints require authentication. To authenticate: + +1. **Login**: Send a POST request to `/api/auth` with your credentials: + ```json + { + "email": "your-email@example.com", + "password": "your-password" + } + ``` + +2. **Use Token**: Include the returned token in subsequent requests using the `Token` header: + ``` + Token: your-authentication-token + ``` + +## API Endpoints Overview + +The API is organized into the following categories: + +- **Authentication** - User login and logout +- **Users** - User management (admin only) +- **Roles** - User role management +- **ANR** - Risk analysis management +- **Assets** - Asset management within analyses +- **Threats** - Threat management +- **Vulnerabilities** - Vulnerability management +- **Measures** - Control/measure management +- **Risks** - Risk assessment and management +- **Recommendations** - Recommendation management +- **Treatment Plan** - Risk treatment planning +- **SOA** - Statement of Applicability +- **Records (GDPR)** - Processing activities records +- **Instances** - Asset instances in risk analyses +- **Snapshots** - Analysis snapshots +- **Statistics** - Statistical data +- And many more... + +## Base URL + +All API endpoints are relative to your MONARC installation's base URL. + +For example: +- Local: `http://localhost/api/...` +- Production: `https://your-domain.com/api/...` + +## API Versioning + +The current API version is documented in the `swagger.yaml` file (version 2.13.3 as of this update). + +## Contributing + +When adding new API endpoints: + +1. Update the route configuration in `config/module.config.php` +2. Add the endpoint documentation to `public/swagger.yaml` +3. Ensure proper authentication and authorization are documented +4. Include request/response examples where applicable + +## Support + +For more information about MONARC: +- Website: https://www.monarc.lu +- Documentation: https://www.monarc.lu/documentation +- GitHub: https://github.com/monarc-project diff --git a/public/swagger-ui.html b/public/swagger-ui.html new file mode 100644 index 0000000..81e15a9 --- /dev/null +++ b/public/swagger-ui.html @@ -0,0 +1,142 @@ + + + + + + MONARC API Documentation + + + +
+

MONARC API Documentation

+ +
+

Welcome to the MONARC (Optimised Risk Analysis Method) API documentation.

+

This API allows you to programmatically interact with MONARC for risk analysis, asset management, threat assessment, and more.

+
+ +
+ Download OpenAPI Specification (YAML) + View in Swagger Editor +
+ +
+

How to View the API Documentation

+
    +
  1. Download the specification: Click the "Download OpenAPI Specification" button above to get the swagger.yaml file.
    2. +
  2. Use Swagger Editor: Click the "View in Swagger Editor" button to view the documentation in the online Swagger Editor.
    3. +
  3. Use Swagger UI locally: If you have Swagger UI installed locally, you can load the swagger.yaml file from /public/swagger.yaml path.
    4. +
  4. Import into API clients: Import the OpenAPI specification into tools like Postman, Insomnia, or other API clients for testing.
    5. +
+ +

Authentication

+

Most API endpoints require authentication via a Token header. To authenticate:

+
    +
  1. Login via POST /api/auth with your email and password
    2. +
  2. Include the returned token in subsequent requests using the Token header
    3. +
+ +

Base URL

+

All API endpoints are relative to the base URL of your MONARC installation.

+
+
+ + + + diff --git a/public/swagger.yaml b/public/swagger.yaml index e776aed..860e0af 100644 --- a/public/swagger.yaml +++ b/public/swagger.yaml @@ -1,22 +1,225 @@ openapi: 3.0.0 info: title: MONARC Project API - version: 1.0.0 + description: | + API for MONARC (Optimised Risk Analysis Method) - a risk analysis tool. + + ## Authentication + Most endpoints require authentication via a Token header. To authenticate: + 1. Login via POST /api/auth to receive a token + 2. Include the token in subsequent requests using the `Token` header + + ## Authorization + Different endpoints require different user roles: + - **superadmin**: Full system administration access + - **userfo**: Standard user with analysis access + - **ceo**: CEO role with specific permissions + version: 2.13.3 + contact: + name: MONARC Project + url: https://www.monarc.lu + license: + name: GNU Affero General Public License version 3 + url: https://www.gnu.org/licenses/agpl-3.0.html + +servers: + - url: / + description: Current server + +components: + securitySchemes: + TokenAuth: + type: apiKey + in: header + name: Token + description: API token obtained from the authentication endpoint + +security: + - TokenAuth: [] + paths: - # ApiAdminUsersController - /api/admin/users: - get: - summary: Retrieve all users + # Authentication + /api/auth: + post: + summary: Authenticate user and get token + description: Login with email and password to receive an authentication token tags: - - Users + - Authentication + security: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - email + - password + properties: + email: + type: string + format: email + example: user@example.com + password: + type: string + format: password + example: password123 + responses: + '200': + description: Authentication successful + content: + application/json: + schema: + type: object + properties: + token: + type: string + description: Authentication token to use in subsequent requests + '401': + description: Invalid credentials + + /api/auth/{id}: + delete: + summary: Logout and invalidate token + description: Logout the user and invalidate the authentication token + tags: + - Authentication parameters: - - in: header - name: Token + - in: path + name: id required: true schema: type: string - security: - - role: [superadmin] + description: User ID or token identifier + responses: + '204': + description: Logout successful + '401': + description: Unauthorized + + # Captcha + /api/captcha: + get: + summary: Get captcha image + tags: + - Captcha + security: [] + responses: + '200': + description: Captcha image + + # User Profile + /api/user/profile: + get: + summary: Get current user profile + tags: + - User Profile + responses: + '200': + description: User profile information + put: + summary: Update current user profile + tags: + - User Profile + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + firstname: + type: string + lastname: + type: string + email: + type: string + format: email + responses: + '200': + description: Profile updated successfully + + /api/user/password/{id}: + put: + summary: Change user password + tags: + - User Profile + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - old + - new + - confirm + properties: + old: + type: string + format: password + new: + type: string + format: password + confirm: + type: string + format: password + responses: + '200': + description: Password changed successfully + + /api/user/activate2FA/{id}: + post: + summary: Activate two-factor authentication + tags: + - User Profile + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: 2FA activated successfully + + /api/user/recoveryCodes/{id}: + get: + summary: Get recovery codes for 2FA + tags: + - User Profile + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Recovery codes + + # Configuration + /api/config: + get: + summary: Get application configuration + tags: + - Configuration + responses: + '200': + description: Application configuration + + # ApiAdminUsersController + /api/users: + get: + summary: Retrieve all users + tags: + - Users responses: '200': description: A list of users @@ -34,39 +237,46 @@ paths: properties: id: type: integer - name: + firstname: + type: string + lastname: type: string email: type: string role: - type: string + type: array + items: + type: string post: summary: Create a new user tags: - Users - parameters: - - in: header - name: Token - required: true - schema: - type: string requestBody: required: true content: application/json: schema: type: object + required: + - firstname + - lastname + - email + - password properties: - name: + firstname: + type: string + lastname: type: string email: type: string + format: email password: type: string + format: password role: - type: string - security: - - role: [superadmin] + type: array + items: + type: string responses: '201': description: User created @@ -77,12 +287,8 @@ paths: properties: id: type: integer - name: - type: string - email: - type: string - /api/admin/users/{id}: + /api/users/{id}: get: summary: Retrieve a user by ID tags: @@ -93,13 +299,6 @@ paths: required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin] responses: '200': description: User details @@ -110,12 +309,16 @@ paths: properties: id: type: integer - name: + firstname: + type: string + lastname: type: string email: type: string role: - type: string + type: array + items: + type: string put: summary: Update a user by ID tags: @@ -126,11 +329,6 @@ paths: required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string requestBody: required: true content: @@ -138,14 +336,17 @@ paths: schema: type: object properties: - name: + firstname: + type: string + lastname: type: string email: type: string + format: email role: - type: string - security: - - role: [superadmin] + type: array + items: + type: string responses: '200': description: User updated @@ -159,18 +360,11 @@ paths: required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin] responses: '204': description: User deleted - /api/admin/users/{id}/reset-password: + /api/users/{id}/resetPassword: post: summary: Reset password for a user by ID tags: @@ -181,31 +375,16 @@ paths: required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin] responses: '200': description: Password reset successful # ApiAdminUsersRolesController - /api/admin/users/roles: + /api/users-roles: get: summary: Get roles for the current user tags: - Roles - parameters: - - in: header - name: token - required: true - schema: - type: string - security: - - role: [superadmin] responses: '200': description: List of roles @@ -219,7 +398,7 @@ paths: items: type: string - /api/admin/users/{id}/roles: + /api/users-roles/{id}: get: summary: Get roles for a specific user by ID tags: @@ -230,13 +409,6 @@ paths: required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin] responses: '200': description: User roles @@ -258,12 +430,6 @@ paths: summary: Handle password-related actions (reset, verify token, change password) tags: - Passwords - parameters: - - in: header - name: Token - required: true - schema: - type: string requestBody: required: true content: @@ -273,63 +439,34 @@ paths: properties: email: type: string + format: email token: type: string password: type: string + format: password confirm: type: string - security: - - role: [superadmin] + format: password responses: '200': description: Successful response '422': description: Validation error - # ApiAnrController - /api/anr: + # Clients + /api/client: get: - summary: Get list of ANRs + summary: Get list of clients tags: - - ANR - parameters: - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin, userfo] # can do it only if it has at lease "r" permissions. + - Clients responses: '200': - description: List of ANRs - content: - application/json: - schema: - type: object - properties: - count: - type: integer - anrs: - type: array - items: - type: object - properties: - id: - type: integer - name: - type: string + description: List of clients post: - summary: Create a new ANR + summary: Create a new client tags: - - ANR - parameters: - - in: header - name: Token - required: true - schema: - type: string + - Clients requestBody: required: true content: @@ -339,68 +476,1885 @@ paths: properties: name: type: string - description: - type: string - security: - - role: [superadmin, userfo] responses: '201': - description: ANR created - content: - application/json: - schema: - type: object - properties: - id: - type: integer + description: Client created - /api/anr/{id}: + /api/client/{id}: get: - summary: Get ANR by ID + summary: Get client by ID tags: - - ANR + - Clients parameters: - in: path name: id required: true schema: type: integer - - in: header - name: Token - required: true - schema: - type: string - security: - - role: [superadmin, userfo] # can do it only if it has at lease "r" permissions. responses: '200': - description: ANR details - content: - application/json: - schema: - type: object - properties: + description: Client details + patch: + summary: Update client by ID + tags: + - Clients + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + responses: + '200': + description: Client updated + delete: + summary: Delete client by ID + tags: + - Clients + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Client deleted + + # System Messages + /api/system-messages: + get: + summary: Get system messages + tags: + - System Messages + responses: + '200': + description: List of system messages + post: + summary: Create a system message + tags: + - System Messages + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + message: + type: string + responses: + '201': + description: System message created + + /api/system-messages/{id}: + get: + summary: Get system message by ID + tags: + - System Messages + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: System message details + patch: + summary: Update system message + tags: + - System Messages + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + message: + type: string + responses: + '200': + description: System message updated + delete: + summary: Delete system message + tags: + - System Messages + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: System message deleted + + # Models + /api/models: + get: + summary: Get list of models + tags: + - Models + responses: + '200': + description: List of models + post: + summary: Create a new model + tags: + - Models + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '201': + description: Model created + + /api/models/{id}: + get: + summary: Get model by ID + tags: + - Models + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Model details + patch: + summary: Update model + tags: + - Models + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Model updated + delete: + summary: Delete model + tags: + - Models + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Model deleted + + # Referentials + /api/referentials: + get: + summary: Get list of referentials + tags: + - Referentials + responses: + '200': + description: List of referentials + + # Guides + /api/guides: + get: + summary: Get list of guides + tags: + - Guides + responses: + '200': + description: List of guides + post: + summary: Create a new guide + tags: + - Guides + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '201': + description: Guide created + + /api/guides/{id}: + get: + summary: Get guide by ID + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Guide details + patch: + summary: Update guide + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Guide updated + delete: + summary: Delete guide + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Guide deleted + + # Guide Items + /api/guides-items: + get: + summary: Get list of guide items + tags: + - Guides + responses: + '200': + description: List of guide items + post: + summary: Create a new guide item + tags: + - Guides + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + description: + type: string + responses: + '201': + description: Guide item created + + /api/guides-items/{id}: + get: + summary: Get guide item by ID + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Guide item details + patch: + summary: Update guide item + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + description: + type: string + responses: + '200': + description: Guide item updated + delete: + summary: Delete guide item + tags: + - Guides + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Guide item deleted + + # Deliveries Models + /api/deliveriesmodels: + get: + summary: Get list of delivery models + tags: + - Deliveries + responses: + '200': + description: List of delivery models + post: + summary: Create a new delivery model + tags: + - Deliveries + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + description: + type: string + responses: + '201': + description: Delivery model created + + /api/deliveriesmodels/{id}: + get: + summary: Get delivery model by ID + tags: + - Deliveries + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Delivery model details + put: + summary: Update delivery model + tags: + - Deliveries + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + description: + type: string + responses: + '200': + description: Delivery model updated + delete: + summary: Delete delivery model + tags: + - Deliveries + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Delivery model deleted + + # ApiAnrController + /api/client-anr: + get: + summary: Get list of ANRs (Risk Analyses) + description: Get all risk analyses accessible to the user + tags: + - ANR + responses: + '200': + description: List of ANRs + content: + application/json: + schema: + type: object + properties: + count: + type: integer + anrs: + type: array + items: + type: object + properties: + id: + type: integer + label: + type: string + post: + summary: Create a new ANR (Risk Analysis) + tags: + - ANR + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - label + properties: + label: + type: string + description: Name/label of the risk analysis + description: + type: string + language: + type: integer + description: Language ID + modelId: + type: integer + description: Model ID to use for the analysis + responses: + '201': + description: ANR created + content: + application/json: + schema: + type: object + properties: + id: + type: integer + + /api/client-anr/{id}: + get: + summary: Retrieve all users + tags: + - Users + parameters: + - in: header + name: Token + required: true + schema: + type: string + security: + - role: [superadmin] + responses: + '200': + description: A list of users + content: + application/json: + schema: + type: object + properties: + count: + type: integer + users: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + email: + type: string + role: + type: string + post: + summary: Create a new user + tags: + - Users + parameters: + - in: header + name: Token + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + email: + type: string + password: + type: string + role: + type: string + security: + - role: [superadmin] + responses: + '201': + description: User created + content: + application/json: + schema: + type: object + properties: id: type: integer name: type: string + email: + type: string + + /api/admin/users/{id}: + /api/client-anr/{id}: + get: + summary: Get ANR by ID + description: Get details of a specific risk analysis + tags: + - ANR + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: ANR details + content: + application/json: + schema: + type: object + properties: + id: + type: integer + label: + type: string description: type: string patch: - summary: Update ANR by ID + summary: Update ANR by ID + description: Update details of a specific risk analysis + tags: + - ANR + parameters: + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + description: + type: string + responses: + '200': + description: ANR updated + delete: + summary: Delete ANR by ID + description: Delete a specific risk analysis + tags: + - ANR + parameters: + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: ANR deleted + + /api/client-duplicate-anr: + post: + summary: Duplicate an ANR + description: Create a copy of an existing risk analysis + tags: + - ANR + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: integer + description: ID of the ANR to duplicate + responses: + '201': + description: ANR duplicated successfully + + # ANR Child Routes - Assets + /api/client-anr/{anrid}/assets: + get: + summary: Get assets for an ANR + tags: + - ANR - Assets + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of assets + post: + summary: Create asset in ANR + tags: + - ANR - Assets + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + code: + type: string + type: + type: integer + responses: + '201': + description: Asset created + + /api/client-anr/{anrid}/assets/{id}: + get: + summary: Get asset by ID + tags: + - ANR - Assets + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Asset details + patch: + summary: Update asset + tags: + - ANR - Assets + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + code: + type: string + responses: + '200': + description: Asset updated + delete: + summary: Delete asset + tags: + - ANR - Assets + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: Asset deleted + + # ANR Child Routes - AMVs (Asset-Measure-Vulnerability) + /api/client-anr/{anrid}/amvs: + get: + summary: Get AMVs for an ANR + tags: + - ANR - AMVs + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of AMVs + post: + summary: Create AMV in ANR + tags: + - ANR - AMVs + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '201': + description: AMV created + + /api/client-anr/{anrid}/amvs/{id}: + delete: + summary: Delete AMV + tags: + - ANR - AMVs + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: AMV deleted + + # ANR Child Routes - Threats + /api/client-anr/{anrid}/threats: + get: + summary: Get threats for an ANR + tags: + - ANR - Threats + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of threats + post: + summary: Create threat in ANR + tags: + - ANR - Threats + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + code: + type: string + responses: + '201': + description: Threat created + + /api/client-anr/{anrid}/threats/{id}: + get: + summary: Get threat by ID + tags: + - ANR - Threats + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Threat details + patch: + summary: Update threat + tags: + - ANR - Threats + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Threat updated + delete: + summary: Delete threat + tags: + - ANR - Threats + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: Threat deleted + + # ANR Child Routes - Vulnerabilities + /api/client-anr/{anrid}/vulnerabilities: + get: + summary: Get vulnerabilities for an ANR + tags: + - ANR - Vulnerabilities + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of vulnerabilities + post: + summary: Create vulnerability in ANR + tags: + - ANR - Vulnerabilities + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + code: + type: string + responses: + '201': + description: Vulnerability created + + /api/client-anr/{anrid}/vulnerabilities/{id}: + get: + summary: Get vulnerability by ID + tags: + - ANR - Vulnerabilities + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Vulnerability details + patch: + summary: Update vulnerability + tags: + - ANR - Vulnerabilities + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Vulnerability updated + delete: + summary: Delete vulnerability + tags: + - ANR - Vulnerabilities + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: Vulnerability deleted + + # ANR Child Routes - Measures + /api/client-anr/{anrid}/measures: + get: + summary: Get measures (controls) for an ANR + tags: + - ANR - Measures + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of measures + post: + summary: Create measure in ANR + tags: + - ANR - Measures + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + code: + type: string + label: + type: string + responses: + '201': + description: Measure created + + /api/client-anr/{anrid}/measures/{id}: + get: + summary: Get measure by ID + tags: + - ANR - Measures + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Measure details + patch: + summary: Update measure + tags: + - ANR - Measures + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Measure updated + delete: + summary: Delete measure + tags: + - ANR - Measures + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: Measure deleted + + # ANR Child Routes - Referentials + /api/client-anr/{anrid}/referentials: + get: + summary: Get referentials for an ANR + tags: + - ANR - Referentials + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of referentials + + /api/client-anr/{anrid}/referentials/{id}: + get: + summary: Get referential by ID + tags: + - ANR - Referentials + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Referential details + + # ANR Child Routes - Instances + /api/client-anr/{anrid}/instances: + get: + summary: Get instances (asset instances) for an ANR + tags: + - ANR - Instances + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of instances + post: + summary: Create instance in ANR + tags: + - ANR - Instances + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + object: + type: string + parent: + type: integer + position: + type: integer + responses: + '201': + description: Instance created + + /api/client-anr/{anrid}/instances/{id}: + get: + summary: Get instance by ID + tags: + - ANR - Instances + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Instance details + patch: + summary: Update instance + tags: + - ANR - Instances + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + responses: + '200': + description: Instance updated + delete: + summary: Delete instance + tags: + - ANR - Instances + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Instance deleted + + # ANR Child Routes - Risks + /api/client-anr/{anrid}/risks: + get: + summary: Get information risks for an ANR + tags: + - ANR - Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of information risks + patch: + summary: Update risk treatment + tags: + - ANR - Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Risk updated + + /api/client-anr/{anrid}/risks/{id}: + delete: + summary: Delete risk + tags: + - ANR - Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Risk deleted + + # ANR Child Routes - Operational Risks + /api/client-anr/{anrid}/risksop: + get: + summary: Get operational risks for an ANR + tags: + - ANR - Operational Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of operational risks + post: + summary: Create operational risk + tags: + - ANR - Operational Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '201': + description: Operational risk created + + /api/client-anr/{anrid}/risksop/{id}: + patch: + summary: Update operational risk + tags: + - ANR - Operational Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Operational risk updated + delete: + summary: Delete operational risk + tags: + - ANR - Operational Risks + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Operational risk deleted + + # ANR Child Routes - Recommendations + /api/client-anr/{anrid}/recommendations: + get: + summary: Get recommendations for an ANR + tags: + - ANR - Recommendations + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of recommendations + post: + summary: Create recommendation + tags: + - ANR - Recommendations + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: + type: string + responses: + '201': + description: Recommendation created + + /api/client-anr/{anrid}/recommendations/{id}: + get: + summary: Get recommendation by ID + tags: + - ANR - Recommendations + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Recommendation details + patch: + summary: Update recommendation + tags: + - ANR - Recommendations + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + description: + type: string + responses: + '200': + description: Recommendation updated + delete: + summary: Delete recommendation + tags: + - ANR - Recommendations + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '204': + description: Recommendation deleted + + # ANR Child Routes - Treatment Plan + /api/client-anr/{anrid}/treatment-plan: + get: + summary: Get treatment plan for an ANR + tags: + - ANR - Treatment Plan + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of treatment plan items + + /api/client-anr/{anrid}/treatment-plan/{id}: + patch: + summary: Update treatment plan item + tags: + - ANR - Treatment Plan + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Treatment plan item updated + + # ANR Child Routes - SOA (Statement of Applicability) + /api/client-anr/{anrid}/soa: + get: + summary: Get SOA for an ANR + tags: + - ANR - SOA + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of SOA items + post: + summary: Create SOA item + tags: + - ANR - SOA + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '201': + description: SOA item created + + /api/client-anr/{anrid}/soa/{id}: + get: + summary: Get SOA item by ID + tags: + - ANR - SOA + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: SOA item details + patch: + summary: Update SOA item + tags: + - ANR - SOA + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: SOA item updated + delete: + summary: Delete SOA item + tags: + - ANR - SOA + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: SOA item deleted + + # ANR Child Routes - Records (GDPR) + /api/client-anr/{anrid}/records: + get: + summary: Get records of processing activities (GDPR) + tags: + - ANR - Records (GDPR) + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of records + post: + summary: Create record of processing activity + tags: + - ANR - Records (GDPR) + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '201': + description: Record created + + /api/client-anr/{anrid}/records/{id}: + get: + summary: Get record by ID + tags: + - ANR - Records (GDPR) + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Record details + patch: + summary: Update record + tags: + - ANR - Records (GDPR) + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + label: + type: string + responses: + '200': + description: Record updated + delete: + summary: Delete record + tags: + - ANR - Records (GDPR) + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Record deleted + + # ANR Child Routes - Scales + /api/client-anr/{anrid}/scales: + get: + summary: Get scales for an ANR + tags: + - ANR - Scales + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of scales + patch: + summary: Update scales tags: - - ANR + - ANR - Scales + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Scales updated + + /api/client-anr/{anrid}/scales/{id}: + get: + summary: Get scale by ID + tags: + - ANR - Scales parameters: + - in: path + name: anrid + required: true + schema: + type: integer - in: path name: id required: true schema: type: integer - - in: header - name: Token + responses: + '200': + description: Scale details + + # ANR Child Routes - Export + /api/client-anr/{anrid}/export: + post: + summary: Export ANR + description: Export the risk analysis to a file + tags: + - ANR - Export/Import + parameters: + - in: path + name: anrid required: true schema: - type: string + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + password: + type: string + responses: + '200': + description: Export file + + # ANR Child Routes - Objects + /api/client-anr/{anrid}/objects: + get: + summary: Get objects for an ANR + tags: + - ANR - Objects + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of objects + post: + summary: Create object in ANR + tags: + - ANR - Objects + parameters: + - in: path + name: anrid + required: true + schema: + type: integer requestBody: required: true content: @@ -410,30 +2364,273 @@ paths: properties: name: type: string - description: + responses: + '201': + description: Object created + + /api/client-anr/{anrid}/objects/{id}: + get: + summary: Get object by ID + tags: + - ANR - Objects + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + responses: + '200': + description: Object details + patch: + summary: Update object + tags: + - ANR - Objects + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: type: string - security: - - role: [superadmin, userfo] # can do it only if it has at lease "rw" permissions. responses: '200': - description: ANR updated + description: Object updated delete: - summary: Delete ANR by ID + summary: Delete object tags: - - ANR + - ANR - Objects parameters: - in: path - name: id + name: anrid required: true schema: type: integer - - in: header - name: Token + - in: path + name: id required: true schema: type: string - security: - - role: [superadmin, userfo] responses: '204': - description: ANR deleted + description: Object deleted + + # ANR Child Routes - Snapshots + /api/client-anr/{anrid}/snapshot: + get: + summary: Get snapshots for an ANR + tags: + - ANR - Snapshots + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: List of snapshots + post: + summary: Create snapshot + tags: + - ANR - Snapshots + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + comment: + type: string + responses: + '201': + description: Snapshot created + + /api/client-anr/{anrid}/snapshot/{id}: + delete: + summary: Delete snapshot + tags: + - ANR - Snapshots + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '204': + description: Snapshot deleted + + /api/client-anr/{anrid}/restore-snapshot/{id}: + post: + summary: Restore ANR from snapshot + tags: + - ANR - Snapshots + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: id + required: true + schema: + type: integer + responses: + '200': + description: Snapshot restored + + # ANR Child Routes - Dashboards + /api/client-anr/{anrid}/risks-dashboard: + get: + summary: Get risks dashboard data + tags: + - ANR - Dashboards + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: Dashboard data + + /api/client-anr/{anrid}/carto-risks-dashboard: + get: + summary: Get cartography of risks dashboard data + tags: + - ANR - Dashboards + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + responses: + '200': + description: Cartography dashboard data + + /api/client-anr/{anrid}/carto-risks-dashboard/{type}: + get: + summary: Get cartography of risks dashboard data by type + tags: + - ANR - Dashboards + parameters: + - in: path + name: anrid + required: true + schema: + type: integer + - in: path + name: type + required: true + schema: + type: string + enum: [all, real, targeted] + responses: + '200': + description: Cartography dashboard data + + # Statistics + /api/stats: + get: + summary: Get statistics + tags: + - Statistics + responses: + '200': + description: Statistics data + + /api/stats/processed: + get: + summary: Get processed statistics list + tags: + - Statistics + responses: + '200': + description: List of processed statistics + + /api/stats/general-settings: + get: + summary: Get general statistics settings + tags: + - Statistics + responses: + '200': + description: Statistics settings + patch: + summary: Update general statistics settings + tags: + - Statistics + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Settings updated + + /api/stats/anrs-settings: + get: + summary: Get ANR statistics settings + tags: + - Statistics + responses: + '200': + description: ANR statistics settings + patch: + summary: Update ANR statistics settings + tags: + - Statistics + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Settings updated + + /api/stats/validate-stats-availability: + get: + summary: Validate statistics availability + tags: + - Statistics + responses: + '200': + description: Validation result From 455757b8aa158451c43275fe19c1d20ccee13a1c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 07:42:28 +0000 Subject: [PATCH 3/3] Update README with API documentation section Co-authored-by: ruslanbaidan <3246171+ruslanbaidan@users.noreply.github.com> --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 21a8a85..de3b5f1 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,25 @@ For installation instructions see You can also use the provided [Virtual Machine](https://vm.monarc.lu). +API Documentation +----------------- + +MONARC provides a comprehensive RESTful API for programmatic access. The API is documented using OpenAPI 3.0 (Swagger) specification. + +- **View API Documentation**: Navigate to `/swagger-ui.html` in your MONARC installation +- **OpenAPI Specification**: Available at `/swagger.yaml` +- **Documentation Guide**: See [public/API_DOCUMENTATION.md](public/API_DOCUMENTATION.md) + +The API allows you to: +- Manage risk analyses (ANR) +- Handle assets, threats, and vulnerabilities +- Manage risks and operational risks +- Create and track recommendations +- Generate reports and exports +- And much more... + +Authentication is token-based. See the API documentation for details on obtaining and using authentication tokens. + Contributing ------------