[backend] Allow escape function in safeEjs for Simple Mailer templates (#13753)

SamuelHassine · SamuelHassine · commit 2cb45394acf4 · 2026-01-10T20:59:42.000+01:00
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -9,6 +9,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  apt_packages:
+    - graphviz
 
 # Build documentation in the client-python/docs/ directory with Sphinx
 sphinx:
diff --git a/client-python/docs/conf.py b/client-python/docs/conf.py
@@ -56,10 +56,26 @@ def get_version():
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.inheritance_diagram",
     "autoapi.extension",
     "sphinx_autodoc_typehints",
 ]
 
+# Graphviz configuration
+graphviz_output_format = "svg"
+inheritance_graph_attrs = {
+    "rankdir": "TB",
+    "size": '"6.0, 8.0"',
+}
+inheritance_node_attrs = {
+    "shape": "box",
+    "fontsize": 10,
+    "height": 0.25,
+    "style": '"setlinewidth(0.5),filled"',
+    "fillcolor": "white",
+}
+
 # Napoleon settings for Google/NumPy style docstrings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
@@ -82,14 +98,17 @@ def get_version():
     "undoc-members",
     "show-inheritance",
     "show-module-summary",
-    "imported-members",
+    "special-members",
 ]
 autoapi_python_class_content = (
     "both"  # Include both class docstring and __init__ docstring
 )
 autoapi_member_order = "bysource"
 autoapi_keep_files = False
 autoapi_add_toctree_entry = True
+# Ignore top-level __init__.py to prevent "Undocumented" for re-exported classes
+# Classes will be documented in their original modules with proper docstrings
+autoapi_ignore = ["*/pycti/__init__.py"]
 
 # Mock imports for modules that can't be installed on ReadTheDocs
 autodoc_mock_imports = [
diff --git a/client-python/docs/pycti/pycti.rst b/client-python/docs/pycti/pycti.rst
@@ -24,52 +24,52 @@ Classes
 =======
 
 - :py:class:`AttackPattern`:
-  Undocumented.
+  Main AttackPattern class for OpenCTI
 
 - :py:class:`Campaign`:
-  Undocumented.
+  Main Campaign class for OpenCTI
 
 - :py:class:`CaseIncident`:
-  Undocumented.
+  Main CaseIncident class for OpenCTI
 
 - :py:class:`CaseRfi`:
-  Undocumented.
+  Main CaseRfi class for OpenCTI
 
 - :py:class:`CaseRft`:
-  Undocumented.
+  Main CaseRft class for OpenCTI
 
 - :py:class:`Channel`:
-  Undocumented.
+  Main Channel class for OpenCTI
 
 - :py:class:`Task`:
-  Undocumented.
+  Main Task class for OpenCTI
 
 - :py:class:`ConnectorType`:
   An enumeration.
 
 - :py:class:`CourseOfAction`:
-  Undocumented.
+  Main CourseOfAction class for OpenCTI
 
 - :py:class:`DataComponent`:
-  Undocumented.
+  Main DataComponent class for OpenCTI
 
 - :py:class:`DataSource`:
-  Undocumented.
+  Main DataSource class for OpenCTI
 
 - :py:class:`ExternalReference`:
-  Undocumented.
+  Main ExternalReference class for OpenCTI
 
 - :py:class:`Feedback`:
-  Undocumented.
+  Main Feedback class for OpenCTI
 
 - :py:class:`Grouping`:
-  Undocumented.
+  Main Grouping class for OpenCTI
 
 - :py:class:`Identity`:
-  Undocumented.
+  Main Identity class for OpenCTI
 
 - :py:class:`Incident`:
-  Undocumented.
+  Main Incident class for OpenCTI
 
 - :py:class:`Indicator`:
   Main Indicator class for OpenCTI
@@ -78,40 +78,40 @@ Classes
   Main Infrastructure class for OpenCTI
 
 - :py:class:`IntrusionSet`:
-  Undocumented.
+  Main IntrusionSet class for OpenCTI
 
 - :py:class:`KillChainPhase`:
-  Undocumented.
+  Main KillChainPhase class for OpenCTI
 
 - :py:class:`Label`:
-  Undocumented.
+  Main Label class for OpenCTI
 
 - :py:class:`Location`:
-  Undocumented.
+  Main Location class for OpenCTI
 
 - :py:class:`Malware`:
-  Undocumented.
+  Main Malware class for OpenCTI
 
 - :py:class:`MalwareAnalysis`:
-  Undocumented.
+  Main MalwareAnalysis class for OpenCTI
 
 - :py:class:`MarkingDefinition`:
-  Undocumented.
+  Main MarkingDefinition class for OpenCTI
 
 - :py:class:`Note`:
-  Undocumented.
+  Main Note class for OpenCTI
 
 - :py:class:`ObservedData`:
-  Undocumented.
+  Main ObservedData class for OpenCTI
 
 - :py:class:`OpenCTIApiClient`:
   Main API client for OpenCTI
 
 - :py:class:`OpenCTIApiConnector`:
-  OpenCTIApiConnector
+  OpenCTI API Connector client
 
 - :py:class:`OpenCTIApiWork`:
-  OpenCTIApiJob
+  OpenCTI API Work client
 
 - :py:class:`OpenCTIConnector`:
   Main class for OpenCTI connector
@@ -120,40 +120,40 @@ Classes
   Python API for OpenCTI connector
 
 - :py:class:`OpenCTIMetricHandler`:
-  Undocumented.
+  Main OpenCTI Metric Handler class
 
 - :py:class:`OpenCTIStix2`:
   Python API for Stix2 in OpenCTI
 
 - :py:class:`OpenCTIStix2Splitter`:
-  Undocumented.
+  Main OpenCTI Stix2 Splitter class
 
 - :py:class:`OpenCTIStix2Update`:
   Python API for Stix2 Update in OpenCTI
 
 - :py:class:`OpenCTIStix2Utils`:
-  Undocumented.
+  Main OpenCTI Stix2 Utils class
 
 - :py:class:`Opinion`:
-  Undocumented.
+  Main Opinion class for OpenCTI
 
 - :py:class:`Report`:
-  Undocumented.
+  Main Report class for OpenCTI
 
 - :py:class:`StixCoreRelationship`:
-  Undocumented.
+  Main StixCoreRelationship class for OpenCTI
 
 - :py:class:`StixCyberObservable`:
-  deprecated [>=6.2 & <6.5]`
+  Deprecated StixCyberObservable class [>=6.2 & <6.5]
 
 - :py:class:`StixNestedRefRelationship`:
-  Undocumented.
+  Main StixNestedRefRelationship class for OpenCTI
 
 - :py:class:`StixCyberObservableTypes`:
   An enumeration.
 
 - :py:class:`StixDomainObject`:
-  Undocumented.
+  Main StixDomainObject class for OpenCTI
 
 - :py:class:`StixMetaTypes`:
   An enumeration.
@@ -162,10 +162,10 @@ Classes
   An enumeration.
 
 - :py:class:`StixObjectOrStixRelationship`:
-  Undocumented.
+  Main StixObjectOrStixRelationship class for OpenCTI
 
 - :py:class:`StixSightingRelationship`:
-  Undocumented.
+  Main StixSightingRelationship class for OpenCTI
 
 - :py:class:`ThreatActor`:
   Main ThreatActor class for OpenCTI
@@ -177,10 +177,10 @@ Classes
   Main ThreatActorIndividual class for OpenCTI
 
 - :py:class:`Tool`:
-  Undocumented.
+  Main Tool class for OpenCTI
 
 - :py:class:`Vulnerability`:
-  Undocumented.
+  Main Vulnerability class for OpenCTI
 
 - :py:class:`CustomObjectCaseIncident`:
   Case-Incident object.
diff --git a/client-python/pycti/utils/opencti_stix2.py b/client-python/pycti/utils/opencti_stix2.py
@@ -49,10 +49,14 @@
 ERROR_TYPE_DRAFT_LOCK = "DRAFT_LOCKED"
 ERROR_TYPE_TIMEOUT = "Request timed out"
 
-# Extensions
-STIX_EXT_OCTI = "extension-definition--ea279b3e-5c71-4632-ac08-831c66a786ba"
-STIX_EXT_OCTI_SCO = "extension-definition--f93e2c80-4231-4f9a-af8b-95c9bd566a82"
-STIX_EXT_MITRE = "extension-definition--322b8f77-262a-4cb8-a915-1e441e00329b"
+#: STIX Extension ID for OpenCTI custom objects and properties
+STIX_EXT_OCTI: str = "extension-definition--ea279b3e-5c71-4632-ac08-831c66a786ba"
+
+#: STIX Extension ID for OpenCTI custom Cyber Observables (SCO)
+STIX_EXT_OCTI_SCO: str = "extension-definition--f93e2c80-4231-4f9a-af8b-95c9bd566a82"
+
+#: STIX Extension ID for MITRE ATT&CK framework objects
+STIX_EXT_MITRE: str = "extension-definition--322b8f77-262a-4cb8-a915-1e441e00329b"
 PROCESSING_COUNT: int = 4
 MAX_PROCESSING_COUNT: int = 100
 
diff --git a/opencti-platform/opencti-graphql/src/utils/safeEjs.ts b/opencti-platform/opencti-graphql/src/utils/safeEjs.ts
@@ -69,6 +69,7 @@ const authorizeGlobals = new Map<string, string | true>([
   ['encodeURIComponent', true],
   ['decodeURI', true],
   ['decodeURIComponent', true],
+  ['escape', true],
 ]);
 
 const forbiddenGlobals = [
@@ -82,7 +83,10 @@ const forbiddenGlobals = [
 
 const noop = () => {};
 
-const createSafeContext = (async: boolean, { maxExecutedStatementCount = 0, maxExecutionDuration = 0, yieldMethod }: SafeOptions) => {
+const createSafeContext = (
+  async: boolean,
+  { maxExecutedStatementCount = 0, maxExecutionDuration = 0, yieldMethod, escape }: SafeOptions & { escape?: (str: string) => string },
+) => {
   let executedStatementCount = 0;
   const checkMaxExecutedStatementCount = maxExecutedStatementCount > 0 ? () => {
     executedStatementCount += 1;
@@ -98,7 +102,7 @@ const createSafeContext = (async: boolean, { maxExecutedStatementCount = 0, maxE
     }
   } : noop;
 
-  return {
+  const context: Record<string, unknown> = {
     [safeName('statement')]: async
       ? async () => {
         checkMaxExecutedStatementCount();
@@ -140,6 +144,13 @@ const createSafeContext = (async: boolean, { maxExecutedStatementCount = 0, maxE
       },
     }),
   };
+
+  // If a custom escape function is provided, make it available in template context
+  if (escape) {
+    context.escape = escape;
+  }
+
+  return context;
 };
 
 const extractEJSCode = (template: string, openTag: string, closeTag: string) => {
diff --git a/opencti-platform/opencti-graphql/tests/01-unit/utils/safeEjs-test.ts b/opencti-platform/opencti-graphql/tests/01-unit/utils/safeEjs-test.ts
