From b9ea18f37eb8599629b8683994547fb629221b2b Mon Sep 17 00:00:00 2001 From: Laurent Bonnet Date: Fri, 20 Sep 2024 17:32:00 +0200 Subject: [PATCH 1/4] [deployment] improve breaking changes documentation --- docs/deployment/breaking-changes.md | 50 +++++++++---------- .../breaking-changes/5.12-filters.md} | 14 ++++-- .../6.2-promote-to-indicator.md | 29 +++++++++++ .../6.2-saml-authentication.md | 16 ++++++ docs/usage/export.md | 2 +- mkdocs.yml | 8 ++- 6 files changed, 84 insertions(+), 35 deletions(-) rename docs/{reference/filters-migration.md => deployment/breaking-changes/5.12-filters.md} (93%) create mode 100644 docs/deployment/breaking-changes/6.2-promote-to-indicator.md create mode 100644 docs/deployment/breaking-changes/6.2-saml-authentication.md diff --git a/docs/deployment/breaking-changes.md b/docs/deployment/breaking-changes.md index 1e6e5e99..dbd7de64 100644 --- a/docs/deployment/breaking-changes.md +++ b/docs/deployment/breaking-changes.md @@ -4,40 +4,36 @@ This section lists breaking changes introduced in OpenCTI, per version starting Please follow the migration guides if you need to upgrade your platform. -## OpenCTI 6.2 - -### Change to the observable "promote" - -The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable. +## Breakdown per version -**GraphQL API** +This table regroups all the breaking changes introduced, with the corresponding version in which the change was implemented. -* Mutation `StixCyberObservableEditMutations.promote` is now deprecated -* New Mutation `StixCyberObservableEditMutations.promoteToIndicator` introduced +| Change | Deprecated in | Changed in | +|:-----------------------------------------------------------------|:--------------|:-----------| +| [SAML authentication parameters](#change-to-SAML-authentication) | 6.2 | 6.5 | +| [Promote Observable API](#change-to-the-observable-promote-API) | | 6.2 | +| [Major changes to Filtering API](#new-filtering-API) | | 5.12 | -**Client-Python API** - -* Client-python method `client.stix_cyber_observable.promote_to_indicator` is now deprecated -* New Client-python method `client.stix_cyber_observable.promote_to_indicator_v2` introduced - +## OpenCTI 6.2 -!!! warning "Discontinued Support" +### Deprecation - Please note that the deprecated methods will be permanently removed in OpenCTI 6.5. + +#### Change to the observable promote API -#### How to migrate - -If you are using custom scripts that make use of the deprecated API methods, please update these scripts. +The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable. -The changes are straightforward: if you are using the return value of the method, you should now expect the new Indicator -instead of the Observable being promoted; adapt your code accordingly. +For more details, see [this migration guide](./breaking-changes/6.2-promote-to-indicator.md). +### Breaking Changes + ### Change to SAML authentication -When `want_assertions_signed` and `want_authn_response_signed` SAML parameter are not present in OpenCTI configuration, -the default is now set to `true` by the underlying library (passport-saml) when previously it was `false` by default. +Upgrading `passport-saml` library introduced a breaking change with respect to the default SAML parameters regarding signing responses and assertions. + +For more details, see [this migration guide](./breaking-changes/6.2-saml-authentication.md). #### How to migrate @@ -45,12 +41,12 @@ If you have issues after upgrade, you can try with both parameters set to `false ## OpenCTI 5.12 -### Major changes to the filtering APi +### Breaking changes -OpenCTI 5.12 introduces a major rework of the **filter engine** with breaking changes to the model. + +#### Major changes to the filtering API +OpenCTI 5.12 introduces a major rework of the **filter engine** with breaking changes to the model. A [dedicated blog post](https://blog.filigran.io/introducing-advanced-filtering-possibilities-in-opencti-552147565faf) describes the reasons behind these changes. -#### How to migrate - -Please read the dedicated [migration guide](../reference/filters-migration.md). +Please read the dedicated [migration guide](./breaking-changes/5.12-filters.md). diff --git a/docs/reference/filters-migration.md b/docs/deployment/breaking-changes/5.12-filters.md similarity index 93% rename from docs/reference/filters-migration.md rename to docs/deployment/breaking-changes/5.12-filters.md index b7f5b4ab..b1452242 100644 --- a/docs/reference/filters-migration.md +++ b/docs/deployment/breaking-changes/5.12-filters.md @@ -1,6 +1,10 @@ -# Filters format migration for OpenCTI 5.12 +# Change to filter model and API -The version 5.12 of OpenCTI introduces breaking changes to the [filters format](./filters.md) used in the API. This documentation describes how you can migrate your scripts or programs that call the OpenCTI API, when updating from a version of OpenCTI inferior to 5.12. +!!! info "" + + * **Changed in**: `OpenCTI 5.12` + +The version 5.12 of OpenCTI introduces breaking changes to the [filters format](../../reference/filters.md) used in the API. This documentation describes how you can migrate your scripts or programs that call the OpenCTI API, when updating from a version of OpenCTI inferior to 5.12. ## Why this migration? @@ -103,7 +107,7 @@ The new filter implementation bring major changes in the way filters are process ## How to migrate your own filters -We wrote a migration script to convert all [stored filters](filters.md#stored-filter-section) created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform. +We wrote a migration script to convert all [stored filters](../../reference/filters.md#stored-filter-section) created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform. However, you might have your own connectors, queries, or python scripts that use the graphql API or the python client. If this is the case, you must change the filter format if you want to run the code against OpenCTI >= 5.12. @@ -111,7 +115,7 @@ However, you might have your own connectors, queries, or python scripts that use To convert filters prior to version 5.12 in the new format: -1. update the `key` field if it has been changed in 5.12 (see the [conversion table](filters-migration.md#conversion-table-section) below), +1. update the `key` field if it has been changed in 5.12 (see the [conversion table](#conversion-table-section) below), 2. rename the field `filterMode` in `mode` 3. if `values` contains `null`, see below for conversion. @@ -323,4 +327,4 @@ These filters are not migrated automatically and are lost when moving to 5.12. T Also, when going to an url with filters in the old format, OpenCTI will display a warning and remove the filter parameters. Only URLs built by OpenCTI 5.12 are compatible with it, so you will need to reconstruct the filters by hand and save / share your updated links. -![URL warning](./assets/filters-migration-url-warning.png) \ No newline at end of file +![URL warning](../../reference/assets/filters-migration-url-warning.png) \ No newline at end of file diff --git a/docs/deployment/breaking-changes/6.2-promote-to-indicator.md b/docs/deployment/breaking-changes/6.2-promote-to-indicator.md new file mode 100644 index 00000000..f9bbf10a --- /dev/null +++ b/docs/deployment/breaking-changes/6.2-promote-to-indicator.md @@ -0,0 +1,29 @@ +# Change to the observable "promote" API + +!!! info "" + + * **Deprecated in**: `OpenCTI 6.2` + * **Removed in**: `OpenCTI 6.5` + +## Description of changes + +The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable. + +**GraphQL API** + +* Mutation `StixCyberObservableEditMutations.promote` is now deprecated +* New Mutation `StixCyberObservableEditMutations.promoteToIndicator` introduced + + +**Client-Python API** + +* Client-python method `client.stix_cyber_observable.promote_to_indicator` is now deprecated +* New Client-python method `client.stix_cyber_observable.promote_to_indicator_v2` introduced + + +## Migration guide + +If you are using custom scripts that make use of the deprecated API methods, please update these scripts. + +The changes are straightforward: if you are using the return value of the method, you should now expect the new Indicator +instead of the Observable being promoted; adapt your code accordingly. \ No newline at end of file diff --git a/docs/deployment/breaking-changes/6.2-saml-authentication.md b/docs/deployment/breaking-changes/6.2-saml-authentication.md new file mode 100644 index 00000000..7ecf6eac --- /dev/null +++ b/docs/deployment/breaking-changes/6.2-saml-authentication.md @@ -0,0 +1,16 @@ +# Change to SAML authentication default parameters + +!!! info "" + + * **Changed in**: `OpenCTI 6.2` + +## Description of changes + +Upgrading `passport-saml` library introduced a breaking change with respect to the default SAML parameters regarding signing responses and assertions. + +When `want_assertions_signed` and `want_authn_response_signed` SAML parameter are not present in OpenCTI configuration, +the default is now set to `true` by `passport-saml` library when previously it was `false` by default. + +## Migrate guide + +If you have issues after upgrade, you can try with both parameters set to `false`. \ No newline at end of file diff --git a/docs/usage/export.md b/docs/usage/export.md index 7640207c..bbed082e 100644 --- a/docs/usage/export.md +++ b/docs/usage/export.md @@ -24,7 +24,7 @@ This opens the export settings panel, where you can customize your export accord - desired export format (text/csv, application/pdf, application/vnd.oasis.stix+json, text/plain) - export type (simple or full), -- the max marking definition levels of the elements to be included in the export (a TLP level, for instance). The list of the available max markings is limited by the user allowed markings and its maximum shareable markings (more details about maximum shareable marking definitions in [data segregation](segregation.md)). For a marking definition type to be taken into account here, a marking definition from this type must be provided. For example, if you select TLP:GREEN for this field, AMBER and RED elements will be excluded but it will not take into account any PAP markings unless one is elected too. +- the max marking definition levels of the elements to be included in the export (a TLP level, for instance). The list of the available max markings is limited by the user allowed markings and its maximum shareable markings (more details about maximum shareable marking definitions in [data segregation](../administration/segregation.md)). For a marking definition type to be taken into account here, a marking definition from this type must be provided. For example, if you select TLP:GREEN for this field, AMBER and RED elements will be excluded but it will not take into account any PAP markings unless one is elected too. - the file marking definition levels of the export (a TLP level, for instance). This marking on the file itself will then restrain the access to it in accordance with users' marking definition levels. For example, if a file has the marking TLP:RED and INTERNAL, a user will need to have these marking to see and access the file in the platform.``` ![customize your export](assets/customize_your_export.png) diff --git a/mkdocs.yml b/mkdocs.yml index def19ab8..facf33a4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -117,7 +117,12 @@ nav: - Configuration: deployment/configuration.md - Authentication: deployment/authentication.md - Upgrade: deployment/upgrade.md - - Breaking changes: deployment/breaking-changes.md + - Breaking changes: + - Index: deployment/breaking-changes.md + - Migration guides: + - Promote to Indicator: deployment/breaking-changes/6.2-promote-to-indicator.md + - SAML authentication: deployment/breaking-changes/6.2-saml-authentication.md + - New filter API: deployment/breaking-changes/5.12-filters.md - Ecosystem: - Connectors: deployment/connectors.md - Integrations: deployment/integrations.md @@ -216,7 +221,6 @@ nav: - GraphQL API: reference/api.md - Filters: - Filters knowledge: reference/filters.md - - Filter migration for 5.12: reference/filters-migration.md - Data Streaming: reference/streaming.md - Deployment and stack: - Usage telemetry: reference/usage-telemetry.md From c2c5c797ee0fe11a93b7377101c2316cc697eb0e Mon Sep 17 00:00:00 2001 From: Laurent Bonnet Date: Mon, 23 Sep 2024 09:00:42 +0200 Subject: [PATCH 2/4] [deployment] fix breaking change versions --- docs/deployment/breaking-changes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/deployment/breaking-changes.md b/docs/deployment/breaking-changes.md index dbd7de64..f19cf405 100644 --- a/docs/deployment/breaking-changes.md +++ b/docs/deployment/breaking-changes.md @@ -10,8 +10,8 @@ This table regroups all the breaking changes introduced, with the corresponding | Change | Deprecated in | Changed in | |:-----------------------------------------------------------------|:--------------|:-----------| -| [SAML authentication parameters](#change-to-SAML-authentication) | 6.2 | 6.5 | -| [Promote Observable API](#change-to-the-observable-promote-API) | | 6.2 | +| [Promote Observable API](#change-to-the-observable-promote-API) | 6.2 | 6.5 | +| [SAML authentication parameters](#change-to-SAML-authentication) | | 6.2 | | [Major changes to Filtering API](#new-filtering-API) | | 5.12 | From 3cbf3b7b6db07424abb15d70ee3d150bf5879ab5 Mon Sep 17 00:00:00 2001 From: Helene Nguyen Date: Mon, 4 Nov 2024 16:50:02 +0100 Subject: [PATCH 3/4] [deployment] add deprecation for connectors --- docs/deployment/breaking-changes.md | 18 +++++++++ .../6.3-removing-some-connectors.md | 37 +++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 docs/deployment/breaking-changes/6.3-removing-some-connectors.md diff --git a/docs/deployment/breaking-changes.md b/docs/deployment/breaking-changes.md index f19cf405..a1276010 100644 --- a/docs/deployment/breaking-changes.md +++ b/docs/deployment/breaking-changes.md @@ -10,11 +10,29 @@ This table regroups all the breaking changes introduced, with the corresponding | Change | Deprecated in | Changed in | |:-----------------------------------------------------------------|:--------------|:-----------| +| [Removing some stream connectors](#removing-some-stream-connectors) | 6.3 | 6.6 | | [Promote Observable API](#change-to-the-observable-promote-API) | 6.2 | 6.5 | | [SAML authentication parameters](#change-to-SAML-authentication) | | 6.2 | | [Major changes to Filtering API](#new-filtering-API) | | 5.12 | + +## OpenCTI 6.3 + +### Deprecation + + +#### Removing some stream connectors + +Some bi-directional stream connectors have been divided into two distinct connectors: + +- An **external import connector** that gathers information from external organizations, applications, or services into OpenCTI. +- A **stream connector** that transfers OpenCTI data to third-party platforms. + +The existing connectors affected by this change will be removed and replaced with these two new connectors. + +For more details, see [this migration guide](./breaking-changes/6.3-removing-some-connectors.md) + ## OpenCTI 6.2 ### Deprecation diff --git a/docs/deployment/breaking-changes/6.3-removing-some-connectors.md b/docs/deployment/breaking-changes/6.3-removing-some-connectors.md new file mode 100644 index 00000000..03ed8d4d --- /dev/null +++ b/docs/deployment/breaking-changes/6.3-removing-some-connectors.md @@ -0,0 +1,37 @@ +# Change to the observable "promote" API + +!!! info "" + + * **Deprecated in**: `OpenCTI 6.3` + * **Removed in**: `OpenCTI 6.6` + +## Description of changes + +Some bi-directional stream connectors have been divided into two distinct connectors: + +- An **external import connector** that gathers information from external organizations, applications, or services into OpenCTI. +- A **stream connector** that transfers OpenCTI data to third-party platforms. + +The existing connectors affected by this change will be removed and replaced with these two new connectors. + +The connectors concerned are: +- **Tanium stream connector** + - Removed: tanium + - Replaced by: + - tanium-incidents external import connector + - tanium-intel stream connector +- H**arfang Lab stream connector** + - Removed: harfang-lab + - Replaced by: + - harfang-lab-incidents external import connector + - harfang-lab-intel stream connector +- **Microsoft Sentinel stream connector** + - Removed: sentinel + - Replaced by: + - sentinel-incidents external import connector + - sentinel-intel stream connector + + +## Migration guide + +If you are using one of those connectors, please start to use the new ones. \ No newline at end of file From e892ac7ab1477da533bd38d96c5007fc23070d60 Mon Sep 17 00:00:00 2001 From: Laurent Bonnet Date: Wed, 6 Nov 2024 08:59:14 +0100 Subject: [PATCH 4/4] [usage] fix formatting --- docs/usage/delete-restore.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/usage/delete-restore.md b/docs/usage/delete-restore.md index f89a3b82..bb98c455 100644 --- a/docs/usage/delete-restore.md +++ b/docs/usage/delete-restore.md @@ -58,5 +58,6 @@ If the missing dependency has been permanently deleted, the object cannot be rec ![restore error: a dependency is in the trash](assets/trash-error-dependency-missing.png) In other words: + * **no partial restore**: the object and _all_ its relationships must be restored in one pass * **no "cascading" restore**: restoring one object does not restore automatically all linked objects in the trash