From 9ac30843d23aecf51eaab74e66cca8cc432e851a Mon Sep 17 00:00:00 2001
From: Samuel Hassine <samuel.hassine@filigran.io>
Date: Sun, 2 Jun 2024 05:26:07 +0100
Subject: [PATCH] Deployed cb6a342 to 6.1.X with MkDocs 1.6.0 and mike
 2.2.0.dev0

---
 .../assets/update-group-new.png               | Bin 35809 -> 44659 bytes
 6.1.X/administration/assets/user-manage.png   | Bin 25649 -> 24683 bytes
 6.1.X/administration/users/index.html         |  23 ++-
 6.1.X/deployment/installation/index.html      |  26 +--
 6.1.X/development/platform/index.html         |  93 ++++++++-
 6.1.X/search/search_index.json                |   2 +-
 6.1.X/sitemap.xml                             | 182 +++++++++---------
 6.1.X/sitemap.xml.gz                          | Bin 935 -> 934 bytes
 .../assets/group-confidence-overrides.png     | Bin 0 -> 43287 bytes
 .../assets/override-confidence-tooltip.png    | Bin 0 -> 20525 bytes
 .../usage/assets/update-confidence-level.png  | Bin 0 -> 31790 bytes
 .../assets/user-confidence-overrides.png      | Bin 0 -> 44485 bytes
 6.1.X/usage/reliability-confidence/index.html |  95 ++++++++-
 13 files changed, 301 insertions(+), 120 deletions(-)
 create mode 100755 6.1.X/usage/assets/group-confidence-overrides.png
 create mode 100755 6.1.X/usage/assets/override-confidence-tooltip.png
 create mode 100755 6.1.X/usage/assets/update-confidence-level.png
 create mode 100755 6.1.X/usage/assets/user-confidence-overrides.png

diff --git a/6.1.X/administration/assets/update-group-new.png b/6.1.X/administration/assets/update-group-new.png
index a7470b7aa623dda9d9aa4293f63752a104a50bc2..6f59ee81b67523133ff6c178efaa8f025f656930 100755
GIT binary patch
literal 44659
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
BN8SJc

literal 35809
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
K18sfd-hTmvPLewS

diff --git a/6.1.X/administration/assets/user-manage.png b/6.1.X/administration/assets/user-manage.png
index 4c5c4096bf5c06361b17d60ca04685fd2c2f54e4..13a79158cdfc826592d48e365240e3625e9c4969 100755
GIT binary patch
literal 24683
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

literal 25649
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
W?lAvo@eo`eWblr99ibc!PW>OS%zl{w

diff --git a/6.1.X/administration/users/index.html b/6.1.X/administration/users/index.html
index 69009b74..54d4eeff 100755
--- a/6.1.X/administration/users/index.html
+++ b/6.1.X/administration/users/index.html
@@ -5109,10 +5109,17 @@ <h3 id="manage-a-user">Manage a user</h3>
 <li>Manage its sessions</li>
 <li>Manage its triggers and digests</li>
 <li>Visualize the history and operations</li>
-<li>Manage its max confidence level (override the value inherited from the group)</li>
+<li>Manage its max confidence levels</li>
 </ul>
 <p><a class="glightbox" href="../assets/user-overveiw-new.png" data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"><img alt="User overview" src="../assets/user-overveiw-new.png" /></a></p>
-<p>In the image below, you can see how to override the value inherited from the group.</p>
+<p>From this view you can edit the user's information by clicking the "Update" button, which opens a panel with several tabs.</p>
+<ul>
+<li>Overview tab: edit all basic information such as the name or language</li>
+<li>Password tab: change the password for this user</li>
+<li>Groups tab: select the groups this user belongs to</li>
+<li>Organization Admin tab: see <a href="./#organization-administration">Organization administration</a></li>
+<li>Confidences tab: manage the user's maximum confidence level and overrides per entity type</li>
+</ul>
 <p><a class="glightbox" href="../assets/user-manage.png" data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"><img alt="manage user" src="../assets/user-manage.png" /></a></p>
 <div class="admonition warning">
 <p class="admonition-title">Mandatory max confidence level</p>
@@ -5207,7 +5214,7 @@ <h2 id="organization-administration">Organization administration</h2>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-21T13:59:23+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-21</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-30T14:27:45+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-30</span>
   </span>
 
     
@@ -5235,6 +5242,11 @@ <h2 id="organization-administration">Organization administration</h2>
     
     <nav>
       
+        <a href="https://github.com/labo-flg" class="md-author" title="@labo-flg">
+          
+          <img src="https://avatars.githubusercontent.com/u/146674147?v=4&size=72" alt="labo-flg">
+        </a>
+      
         <a href="https://github.com/Lhorus6" class="md-author" title="@Lhorus6">
           
           <img src="https://avatars.githubusercontent.com/u/70956706?v=4&size=72" alt="Lhorus6">
@@ -5250,11 +5262,6 @@ <h2 id="organization-administration">Organization administration</h2>
           <img src="https://avatars.githubusercontent.com/u/148041607?v=4&size=72" alt="nino-filigran">
         </a>
       
-        <a href="https://github.com/yassine-ouaamou" class="md-author" title="@yassine-ouaamou">
-          
-          <img src="https://avatars.githubusercontent.com/u/7083405?v=4&size=72" alt="yassine-ouaamou">
-        </a>
-      
       
       
         
diff --git a/6.1.X/deployment/installation/index.html b/6.1.X/deployment/installation/index.html
index 619a150f..c9ab1917 100755
--- a/6.1.X/deployment/installation/index.html
+++ b/6.1.X/deployment/installation/index.html
@@ -5472,7 +5472,7 @@ <h2 id="using-docker">Using Docker</h2>
 <p>OpenCTI can be deployed using the <em>docker-compose</em> command.</p>
 <div class="admonition note">
 <p class="admonition-title">Deploy FIPS 140-2 compliant components</p>
-<p>We are providing FIPS 140-2 compliant images, please read the <a href="../../reference/fips/">dedicated documentation</a> to understand how to deploy OpenCTI in FIPS-compliant mode.</p>
+<p>We provide FIPS 140-2 compliant images. Please read the <a href="../../reference/fips/">dedicated documentation</a> to understand how to deploy OpenCTI in FIPS-compliant mode.</p>
 </div>
 <h3 id="pre-requisites">Pre-requisites</h3>
 <p><strong><span class="twemoji middle"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14.62 8.35c-.42.28-1.75 1.04-1.95 1.19-.39.31-.75.29-1.14-.01-.2-.16-1.53-.92-1.95-1.19-.48-.31-.45-.7.08-.92 1.64-.69 3.28-.64 4.91.03.49.21.51.6.05.9m7.22 7.28c-.93-2.09-2.2-3.99-3.84-5.66a4.31 4.31 0 0 1-1.06-1.88c-.1-.33-.17-.67-.24-1.01-.2-.88-.29-1.78-.7-2.61-.73-1.58-2-2.4-3.84-2.47-1.81.05-3.16.81-3.95 2.4-.21.43-.36.88-.46 1.34-.17.76-.32 1.55-.5 2.32-.15.65-.45 1.21-.96 1.71-1.61 1.57-2.9 3.37-3.88 5.35-.14.29-.28.58-.37.88-.19.66.29 1.12.99.96.44-.09.88-.18 1.3-.31.41-.15.57-.05.67.35.65 2.15 2.07 3.66 4.24 4.5 4.12 1.56 8.93-.66 9.97-4.58.07-.27.17-.37.47-.27.46.14.93.24 1.4.35.49.09.85-.16.92-.64.03-.26-.06-.49-.16-.73"/></svg></span> Linux</strong></p>
@@ -5490,16 +5490,16 @@ <h3 id="configure-the-environment">Configure the environment</h3>
 <div class="admonition warning">
 <p class="admonition-title">ElasticSearch / OpenSearch configuration</p>
 <ul>
-<li>We highly recommend to put the ElasticSearch / OpenSearch following parameter:</li>
+<li>We strongly recommend that you add the following ElasticSearch / OpenSearch parameter:</li>
 </ul>
 <div class="highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>thread_pool.search.queue_size<span class="o">=</span><span class="m">5000</span>
 </span></code></pre></div>
 <ul>
-<li>Check the <a href="../rollover/#opencti-integration-user-permissions-in-opensearchelasticsearch">OpenCTI Integration User Permissions in OpenSearch/ElasticSearch</a> for detailed information about the necessary user permissions for the OpenSearch/ElasticSearch integration.</li>
+<li>Check the <a href="../rollover/#opencti-integration-user-permissions-in-opensearchelasticsearch">OpenCTI Integration User Permissions in OpenSearch/ElasticSearch</a> for detailed information about the user permissions required for the OpenSearch/ElasticSearch integration.</li>
 </ul>
 </div>
 <p>Before running the <code>docker-compose</code> command, the <code>docker-compose.yml</code> file should be configured. By default, the <code>docker-compose.yml</code> file is using environment variables available in the file <code>.env.sample</code>.</p>
-<p>You can either rename the file <code>.env.sample</code> in <code>.env</code> and put the expected values or just fill directly the <code>docker-compose.yml</code> with the values corresponding to your environment.</p>
+<p>You can either rename the file <code>.env.sample</code> as <code>.env</code> and enter the values or just directly edit the <code>docker-compose.yml</code> with the values for your environment.</p>
 <div class="admonition note">
 <p class="admonition-title">Configuration static parameters</p>
 <p>The complete list of available static parameters is available in the <a href="../configuration/">configuration</a> section.</p>
@@ -5530,7 +5530,7 @@ <h3 id="configure-the-environment">Configure the environment</h3>
 <p>If your <code>docker-compose</code> deployment does not support <code>.env</code> files, just export all environment variables before launching the platform:</p>
 <div class="highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="nb">export</span><span class="w"> </span><span class="k">$(</span>cat<span class="w"> </span>.env<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>-v<span class="w"> </span><span class="s2">&quot;#&quot;</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>xargs<span class="k">)</span>
 </span></code></pre></div>
-<p>As OpenCTI has a dependency on ElasticSearch, you have to set the <code>vm.max_map_count</code> before running the containers, as mentioned in the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode">ElasticSearch documentation</a>.</p>
+<p>As OpenCTI has a dependency on ElasticSearch, you have to set <code>vm.max_map_count</code> before running the containers, as mentioned in the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode">ElasticSearch documentation</a>.</p>
 <div class="highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>sudo<span class="w"> </span>sysctl<span class="w"> </span>-w<span class="w"> </span>vm.max_map_count<span class="o">=</span><span class="m">1048575</span>
 </span></code></pre></div>
 <p>To make this parameter persistent, add the following to the end of your <code>/etc/sysctl.conf</code>:</p>
@@ -5538,7 +5538,7 @@ <h3 id="configure-the-environment">Configure the environment</h3>
 </span></code></pre></div>
 <h3 id="persist-data">Persist data</h3>
 <p>The default for OpenCTI data is to be persistent.</p>
-<p>In the <code>docker-compose.yml</code>, you will find at the end the list of necessary persistent volumes for the dependencies:</p>
+<p>In <code>docker-compose.yml</code>, you will find the list of necessary persistent volumes for the dependencies at the end:</p>
 <div class="highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="nt">volumes</span><span class="p">:</span>
 </span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w">  </span><span class="nt">esdata</span><span class="p">:</span><span class="w">     </span><span class="c1"># ElasticSearch data</span>
 </span><span id="__span-7-3"><a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="w">  </span><span class="nt">s3data</span><span class="p">:</span><span class="w">     </span><span class="c1"># S3 bucket data</span>
@@ -5715,7 +5715,7 @@ <h4 id="rabbitmq">RabbitMQ</h4>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-14T14:56:22+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-14</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-29T17:43:32+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-29</span>
   </span>
 
     
@@ -5743,6 +5743,11 @@ <h4 id="rabbitmq">RabbitMQ</h4>
     
     <nav>
       
+        <a href="https://github.com/damians-filigran" class="md-author" title="@damians-filigran">
+          
+          <img src="https://avatars.githubusercontent.com/u/170478556?v=4&size=72" alt="damians-filigran">
+        </a>
+      
         <a href="https://github.com/SamuelHassine" class="md-author" title="@SamuelHassine">
           
           <img src="https://avatars.githubusercontent.com/u/1334279?v=4&size=72" alt="SamuelHassine">
@@ -5758,16 +5763,11 @@ <h4 id="rabbitmq">RabbitMQ</h4>
           <img src="https://avatars.githubusercontent.com/u/3634942?v=4&size=72" alt="aHenryJard">
         </a>
       
-        <a href="https://github.com/c-neto" class="md-author" title="@c-neto">
-          
-          <img src="https://avatars.githubusercontent.com/u/26532223?v=4&size=72" alt="c-neto">
-        </a>
-      
       
       
         
           <a href="https://github.com/OpenCTI-Platform/docs/blob/main/docs/deployment/installation.md" class="md-author md-author--more">
-            +4
+            +5
           </a>
         
       
diff --git a/6.1.X/development/platform/index.html b/6.1.X/development/platform/index.html
index 5250ca5f..f38638c7 100755
--- a/6.1.X/development/platform/index.html
+++ b/6.1.X/development/platform/index.html
@@ -4759,6 +4759,45 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#continous-integration-and-features-cross-repository" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Continous Integration and features cross repository
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Continous Integration and features cross repository">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#naming-convention-of-branch" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Naming convention of branch
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#labels" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Labels
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -5182,6 +5221,45 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#continous-integration-and-features-cross-repository" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Continous Integration and features cross repository
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Continous Integration and features cross repository">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#naming-convention-of-branch" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Naming convention of branch
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#labels" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Labels
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -5441,6 +5519,14 @@ <h2 id="production-build">Production build</h2>
 <div class="highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>../opencti-graphql
 </span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>$<span class="w"> </span>yarn<span class="w"> </span>serv
 </span></code></pre></div>
+<h2 id="continous-integration-and-features-cross-repository">Continous Integration and features cross repository</h2>
+<p>When a feature requires changes in two or more repository in opencti, connectors and client-python; then some specific convention must be use to have the continuous integration build them all together.</p>
+<h3 id="naming-convention-of-branch">Naming convention of branch</h3>
+<p>The Pull Request on <strong><em>opencti</em></strong> repository should be (issue or bug)/number + optional, example: <code>issue/7062-contributing</code></p>
+<p>The pull request on <strong><em>connector</em></strong> or <strong><em>client-python</em></strong> should refer to opencti one by starting with "opencti/" and then the same name. Example: <code>opencti/issue/7062-contributing</code></p>
+<p>Note that if there are several matches, the first one is taken. So for example having <code>issue/7062-contributing</code> and <code>issue/7062</code> that are both marked as "multi-repository" is not a good idea.</p>
+<h3 id="labels">Labels</h3>
+<p>All Pull Requests involved must have the label <code>multi-repository</code> added in GitHub.</p>
 
 
 
@@ -5463,7 +5549,7 @@ <h2 id="production-build">Production build</h2>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-03-12T08:05:56+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-03-12</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-30T12:30:48+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-30</span>
   </span>
 
     
@@ -5491,6 +5577,11 @@ <h2 id="production-build">Production build</h2>
     
     <nav>
       
+        <a href="https://github.com/aHenryJard" class="md-author" title="@aHenryJard">
+          
+          <img src="https://avatars.githubusercontent.com/u/3634942?v=4&size=72" alt="aHenryJard">
+        </a>
+      
         <a href="https://github.com/labo-flg" class="md-author" title="@labo-flg">
           
           <img src="https://avatars.githubusercontent.com/u/146674147?v=4&size=72" alt="labo-flg">
diff --git a/6.1.X/search/search_index.json b/6.1.X/search/search_index.json
index 855e399e..f4f8a8e4 100755
--- a/6.1.X/search/search_index.json
+++ b/6.1.X/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"OpenCTI Documentation Space","text":"<p>Welcome to the OpenCTI Documentation space. Here you will be able to find all documents, meeting notes and presentations about the platform.</p> <p>Release notes</p> <p>Please, be sure to also take a look at the OpenCTI releases notes, they may contain important information about releases and deployments.</p>"},{"location":"#introduction","title":"Introduction","text":"<p>OpenCTI is an open source platform allowing organizations to manage their cyber threat intelligence knowledge and observables. It has been created in order to structure, store, organize and visualize technical and non-technical information about cyber threats.</p>"},{"location":"#getting-started","title":"Getting started","text":"<ul> <li> <p> Deployment &amp; Setup</p> <p>Learn how to deploy and configure the platform as well as launch connectors to get the first data in OpenCTI.</p> <p> Deploy now</p> </li> <li> <p> User Guide</p> <p>Understand how to use the platform, explore the knowledge, import and export information, create dashboard, etc.</p> <p> Explore</p> </li> <li> <p> Administration</p> <p>Know how to administrate OpenCTI, create users and groups using RBAC / segregation, put retention policies and custom taxonomies.</p> <p> Customize</p> </li> </ul> <p>Need more help?</p> <p>We are doing our best to keep this documentation complete, accurate and up to date. </p> <p>If you still have questions or you find something which is not sufficiently explained, join the Filigran Community on Slack.</p>"},{"location":"#latest-blog-posts","title":"Latest blog posts","text":"<p>All tutorials are published directly on the Medium blog, this section provides a comprehensive list of the most important ones.</p> <ul> <li> <p>Introducing decay rules implementation for Indicators in OpenCTI <sub><sup>Mar 25, 2024</sup></sub></p> <p>Cyber Threat Intelligence is made to be used. To be useful, it must be relevant and on time. It is why managing the lifecycle of Indicators of Compromise...</p> <p> Read</p> </li> <li> <p>Introducing advanced filtering possibilities in OpenCTI <sub><sup>Feb 5, 2024</sup></sub></p> <p>CTI databases are usually vast and made of complex, inter-dependent objects ingested from various sources. In this challenging context, cyber analysts need...</p> <p> Read</p> </li> <li> <p>Breaking change: evolution of the way Connector, Streams and Feeds import data in OpenCTI <sub><sup>Jan 29, 2024</sup></sub></p> <p>How Connectors, Feeds and Streams use Confidence level currently...</p> <p> Read</p> </li> </ul>"},{"location":"#additional-resources","title":"Additional resources","text":"<p>Below, you will find external resources which may be useful along your OpenCTI journey.</p> <p> OpenCTI Ecosystem List of available connectors and integrations to expand platform usage.</p> <p> Training Courses Training courses for analysts and administrators in the Filigran training center.</p> <p> Video materials Set of video illustrating the implementation of use cases and platform capabilities.</p> <p></p>"},{"location":"administration/csv-mappers/","title":"CSV Mappers","text":"<p>In OpenCTI, CSV Mappers allow to parse CSV files in a STIX 2.1 Object. The mappers are created and configured by users with the Manage CSV mapper capability. Then, they are available to users who import CSV files, for instance inside a report or in the global import view.</p>"},{"location":"administration/csv-mappers/#principles","title":"Principles","text":"<p>The mapper contains representations of STIX 2.1 entities and relationships, in order for the parser to properly extract them. One mapper is dedicated to parsing a specific CSV file structure, and thus dedicated mappers should be created for every specific CSV structure you might need to ingest in the platform.</p>"},{"location":"administration/csv-mappers/#create-a-new-csv-mapper","title":"Create a new CSV Mapper","text":"<p>In menu Data, select the submenu Processing, and on the right menu select CSV Mappers. You are presented with a list of all the mappers set in the platform. Note that you can delete or update any mapper from the context menu via the burger button beside each mapper.</p> <p>Click on the button + in the bottom-right corner to add a new Mapper.</p> <p>Enter a name for your mapper and some basic information about your CSV files: </p> <ul> <li>The line separator used (defaults to the standard comma character)</li> <li>The presence of a header on the first line</li> </ul> <p>Header management</p> <p>The parser will not extract any information from the CSV header if any, it will just skip the first line during parsing.</p> <p></p> <p>Then, you need to create every representation, one per entity and relationship type represented in the CSV file. Click on the + button to add an empty representation in the list, and click on the chevron to expand the section and configure the representation.</p> <p>Depending on the entity type, the form contains the fields that are either required (input outlined in red) or optional. For each field, set the corresponding columns mapping (the letter-based index of the column in the CSV table, as presented in common spreadsheet tools). </p> <p>References to other entities should be picked from the list of all the other representations already defined earlier in the mapper.</p> <p>You can do the same for all the relationships between entities that might be defined in this particular CSV file structure.</p> <p></p> <p>Fields might have options besides the mandatory column index, to help extract relevant data:</p> <ul> <li>Date values are expected in ISO 8601 format, but you can set your own format to the time parser</li> <li>Multiple values can be extracted by specifying the separator used inside the cell (e.g. <code>+</code> or <code>|</code>)</li> </ul> <p>Or to set default values in case some data is missing in the imported file.</p> <p></p>"},{"location":"administration/csv-mappers/#csv-mapper-validity","title":"CSV Mapper validity","text":"<p>The only parameter required to save a CSV Mapper is a name. The creation and refinement of its representations can be done iteratively.</p> <p>Nonetheless, all CSV Mappers go through a quick validation that checks if all the representations have all their mandatory fields set.  Only valid mappers can be run by the users on their CSV files.</p> <p>Mapper validity is visible in the list of CSV Mappers as shown below.</p> <p></p>"},{"location":"administration/csv-mappers/#test-your-csv-mapper","title":"Test your CSV mapper","text":"<p>In the creation or edition form, hit the button Test to open a dialog. Select a sample CSV file and hit the Test button.</p> <p>The code block contains the raw result of the parsing attempt, in the form of a STIX 2.1 bundle in JSON format.</p> <p>You can then check if the extracted values match the expected entities and relationships.</p> <p></p> <p>Partial test</p> <p>The test conducted in this window relies only on the translation of CSV data according to the chosen representation in the mapper. It does not take into account checks for accurate entity formatting (e.g. IPv4) or specific entity configurations (e.g. mandatory \"description\" field on reports). Consequently, the entities visible in the test window may not be created during the actual import process.</p> <p>Test with a small file</p> <p>We strongly recommend limiting test files to 100 lines and 1MB. Otherwise, the browser may crash.</p>"},{"location":"administration/csv-mappers/#use-a-mapper-for-importing-a-csv-file","title":"Use a mapper for importing a CSV file","text":"<p>You can change the default configuration of the import csv connector in your configuration file.</p> <pre><code>\"import_csv_built_in_connector\": {\n  \"enabled\": true, \n  \"interval\": 10000, \n  \"validate_before_import\": false\n},\n</code></pre> <p>In Data import section, or Data tab of an entity, when you upload a CSV, you can select a mapper to apply to the file.  The file will then be parsed following the representation rules set in the mapper.</p> <p>By default, the imported elements will be added in a new Analyst Workbench where you will be able to check the result of the import.</p>"},{"location":"administration/csv-mappers/#default-values-for-attributes","title":"Default values for attributes","text":"<p>In the case of the CSV file misses some data, you can complete it with default values. To achieve this, you have two possibilities:</p> <ul> <li>Set default values in the settings of the entities,</li> <li>Set default values directly in the CSV mapper.</li> </ul>"},{"location":"administration/csv-mappers/#set-default-values-in-the-settings-of-the-entities","title":"Set default values in the settings of the entities","text":"<p>Default value mechanisms</p> <p>Note that adding default values in settings have an impact at entity creation globally on the platform, not only on CSV mappers. If you want to apply those default values only at CSV mapper level, please use the second option.</p> <p>In settings &gt; Customization, you can select an entity type and then set default values for its attributes.</p> <p></p> <p>In the configuration of the entity, you have access to the entity's attributes that can be managed.</p> <p>Click on the attribute to add a default value information.</p> <p></p> <p>Enter the default value in the input and save the update.</p> <p></p> <p>The value filled will be used in the case where the CSV file lacks data for this attribute.</p>"},{"location":"administration/csv-mappers/#set-specific-default-values-directly-in-the-csv-mapper","title":"Set specific default values directly in the CSV mapper","text":"<p>Information retained in case of default value</p> <p>If you fill a default value in entity settings and the CSV mapper, the one from CSV mapper will be used.</p> <p>In the mapper form, you will see next to the column index input a gear icon to add extra information for the attribute. If the attribute can have a customizable default value, then you will be able to set one here.</p> <p></p> <p>The example above shows the case of the attribute <code>architecture implementation</code> of a malware. You have some information here. First, it seems we have a default value already set in entity settings for this attribute with the value <code>[powerpc, x86]</code>. However, we want to override this value with another one for our case: <code>[alpha]</code>.</p>"},{"location":"administration/csv-mappers/#specific-case-of-marking-definitions","title":"Specific case of marking definitions","text":"<p>For marking definitions, setting a default value is different from other attributes. We are not choosing a particular marking definition to use if none is specified in the CSV file. Instead, we will choose a default policy. Two option are available:</p> <ul> <li>Use the default marking definitions of the user. In this case the default marking definitions of the connected user importing the CSV file will be used,</li> <li>Let the user choose marking definitions. Here the user importing the CSV file will choose marking definitions (among the ones they can see) when selecting the CSV mapper.</li> </ul> <p></p>"},{"location":"administration/csv-mappers/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To additional content on entity customization, refers to the Customize entities page in the Administration section of the documentation.</li> </ul>"},{"location":"administration/decay-rules/","title":"Decay rules","text":"<p>Decay rules are used to update automatically indicators score in order to represent their lifecycle.</p>"},{"location":"administration/decay-rules/#configuration","title":"Configuration","text":"<p>Decay rules can be configured in the \"Settings &gt; Customization &gt; Decay rule\" menu.</p> <p></p> <p>There are built-in decay rules that can't be modified and are applied by default to indicators depending on their main observable type. Decay rules are applied from highest to lowest order (the lowest being 0).</p> <p>You can create new decay rules with higher order to apply them along with (or instead of) the built-in rules.</p> <p></p> <p>When you create a decay rule, you can specify on which indicators' main observable types it will apply. If you don't enter any, it will apply to all indicators.</p> <p>You can also add reaction points which represent the scores at which indicators are updated. For example, if you add one reaction point at 60 and another one at 40, indicators that have an initial score of 80 will be updated with a score of 60, then 40, depending on the decay curve.</p> <p>The decay curve is based on two parameters: </p> <ul> <li>the decay factor, which represents the speed at which the score falls, and</li> <li>the lifetime, which represents the time (in days) during which the value will be lowered until it reaches 0.</li> </ul> <p>Finally, the revoke score is the score at which the indicator can be revoked automatically.</p> <p></p> <p>Once you have created a new decay rule, you will be able to view its details, along with a life curve graph showing the score evolution over time.</p> <p>You will also be able to edit your rule, change all its parameters and order, activate or deactivate it (only activated rules are applied), or delete it.</p> <p></p> <p>Indicator decay manager</p> <p>Decay rules are only applied, and indicators score updated, if indicator decay manager is enabled (enabled by default). </p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/enterprise/","title":"Enterprise edition","text":"<p>Filigran</p> <p>Filigran is providing an Enterprise Edition of the platform, whether on-premise or in the SaaS.</p>"},{"location":"administration/enterprise/#what-is-opencti-ee","title":"What is OpenCTI EE?","text":"<p>OpenCTI Enterprise Edition is based on the open core concept. This means that the source code of OCTI EE remains open source and included in the main GitHub repository of the platform but is published under a specific license. As specified in the GitHub license file:</p> <ul> <li>The OpenCTI Community Edition is licensed under the Apache License, Version 2.0 (the \u201cApache License\u201d).</li> <li>The OpenCTI Enterprise Edition is licensed under the OpenCTI Enterprise Edition License (the \u201cEnterprise Edition Licensee\u201d).</li> </ul> <p>The source files in this repository have a header indicating which license they are under. If no such header is provided, this means that the file belongs to the Community Edition under the Apache License, Version 2.0.</p> <p>We wrote a complete article to explain the enterprise edition, feel free to read it to have more information</p>"},{"location":"administration/enterprise/#ee-activation","title":"EE Activation","text":"<p>Enterprise edition is easy to activate. You need to go the platform settings and click on the Activate button.</p> <p></p> <p>Then you will need to agree to the Filigran EULA. </p> <p></p> <p>As a reminder:</p> <ul> <li>OpenCTI EE is free-to-use for development, testing and research purposes as well as for non-profit organizations.</li> <li>OpenCTI EE is included for all Filigran SaaS customers without additional fee.</li> <li>For all other usages, OpenCTI EE is reserved to organizations that have signed a Filigran Enterprise agreement.</li> </ul>"},{"location":"administration/enterprise/#available-features","title":"Available features","text":""},{"location":"administration/enterprise/#activity-monitoring","title":"Activity monitoring","text":"<p>Audit logs help you answer \"who did what, where, and when?\" within your data with the maximum level of transparency. Please read Activity monitoring page to get all information.</p>"},{"location":"administration/enterprise/#playbooks-and-automation","title":"Playbooks and automation","text":"<p>OpenCTI playbooks are flexible automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform. Please read Playbook automation page to get all information.</p>"},{"location":"administration/enterprise/#organizations-management-and-segregation","title":"Organizations management and segregation","text":"<p>Organizations segregation is a way to segregate your data considering the organization associated to the users. Useful when your platform aims to share data to multiple organizations that have access to the same OpenCTI platform. Please read Organizations RBAC to get more information.</p>"},{"location":"administration/enterprise/#full-text-indexing","title":"Full text indexing","text":"<p>Full text indexing grants improved searches across structured and unstructured data. OpenCTI classic searches are based on metadata fields (e.g. title, description, type) while advanced indexing capability  enables  searches  to  be  extended  to  the document\u2019s contents. Please read File indexing to get all information.</p>"},{"location":"administration/enterprise/#more-to-come","title":"More to come","text":"<p>More features will be available in OpenCTI in the future. Features like:</p> <ul> <li>Generative AI for correlation and content generation.</li> <li>Supervised machine learning for natural language processing.</li> </ul>"},{"location":"administration/entities/","title":"Customize entities","text":""},{"location":"administration/entities/#introduction","title":"Introduction","text":"<p>A variety of entity customization options are available to optimize data representation, workflow management, and enhance overall user experience. Whether you're fine-tuning processing statuses, configuring entities' attributes, or hiding entities, OpenCTI's customization capabilities provide the flexibility you need to create a tailored environment for your threat intelligence and cybersecurity workflows.</p> <p>The following chapter aims to provide readers with an understanding of the available customization options by entity type. Customize entities can be done in \"Settings &gt; Customization\".</p> <p></p>"},{"location":"administration/entities/#hidden-in-interface","title":"Hidden in interface","text":"<p>This configuration allows to hide a specific entity type throughout the entire platform. It provides a potent means to simplify the interface and tailor it to your domain expertise. For instance, if you have no interest in disinformation campaigns, you can conceal related entities such as Narratives and Channels from the menus.</p> <p>You can specify which entities to hide on a platform-wide basis from \"Settings &gt; Customization\" and from \"Settings &gt; Parameters\", providing you with a list of hidden entities. Furthermore, you can designate hidden entities for specific Groups and Organizations from \"Settings &gt; Security &gt; Groups/Organizations\" by editing a Group/Organization.</p> <p>An overview of hidden entity types is available in the \"Hidden entity types\" field in \"Settings &gt; Parameters.\"</p>"},{"location":"administration/entities/#automatic-references-at-file-upload","title":"Automatic references at file upload","text":"<p>This configuration enables an entity to automatically construct an external reference from the uploaded file.</p>"},{"location":"administration/entities/#enforce-references","title":"Enforce references","text":"<p>This configuration enables the requirement of a reference message on an entity creation or modification. This option is helpful if you want to keep a strong consistency and traceability of your knowledge and is well suited for manual creation and update.</p> <p></p> <p></p>"},{"location":"administration/entities/#workflow","title":"Workflow","text":"<p>For now, OpenCTI has a simple workflow approach. They're represented by the \"Processing status\" field embedded in each object. By default, this field is disabled for most objects but can be activated through the platform settings:</p> <ol> <li>Navigate to \"Settings &gt; Customization &gt; Entity types &gt; [Desired object type].\"</li> <li>Click on the small pink pen icon next to \"Workflow\" to access the object customization window.</li> <li>Add and configure the desired statuses, defining their order within the workflow.</li> </ol> <p></p> <p>In addition, the available statuses are defined by a collection of status templates visible in \"Settings &gt; Taxonomies &gt; Status templates\". This collection can be customized.</p> <p></p>"},{"location":"administration/entities/#attributes","title":"Attributes","text":"<p>Each attribute in an Entity offers several customization options:</p> <ul> <li>It can be set as mandatory if not already defined as such in the STIX standard.</li> <li>A default value can be established to streamline entity creation through the creation forms.</li> <li>Different thresholds and their corresponding labels for scalable attributes can be defined.</li> </ul> <p></p>"},{"location":"administration/entities/#confidence-scale-configuration","title":"Confidence scale configuration","text":"<p>Confidence scale can be customized for each entity type by selecting another scale template or by editing directly the scale values. Once you have customized your scale, click on \"Update\" to save your configuration.</p> <p></p> <p>Max confidence level</p> <p>The above scale also needs to take into account the confidence level per user. To understand the concept, please navigate to this page</p>"},{"location":"administration/file-indexing/","title":"File indexing","text":"<p>Enterprise edition</p> <p>Platform segregation by organization is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all the information.</p>"},{"location":"administration/file-indexing/#files-search-requirements","title":"Files search requirements","text":"<p>In order to search in files, we need to extract and index files text content, which requires to have one of these database configurations :</p> <ul> <li>Elasticsearch &gt;= 8.4</li> <li>Elasticsearch &lt; 8.4 with ingest-attachment plugin</li> <li>OpenSearch with ingest-attachment plugin</li> </ul>"},{"location":"administration/file-indexing/#file-indexing-configuration","title":"File indexing configuration","text":"<p>File indexing can be configured via the <code>File indexing</code> tab in the <code>Settings</code> menu.</p> <p>The configuration and impact panel shows all file types that can be indexed, as well as the volume of storage used.</p> <p>It is also possible to include or exclude files uploaded from the global Data import panel and that are not associated with a specific entity in the platform.</p> <p>Finally, it is possible to set a maximum file size for indexing (5 Mb by default).</p> <p>Currently supported content types : <code>application/pdf</code>, <code>text/plain</code>, <code>text/csv</code>, <code>text/html</code>, <code>application/vnd.ms-excel</code>, <code>application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</code> (excel sheets).</p> <p></p> <p>Once indexing has been launched by pressing the <code>Start</code> button, you can follow its progress. </p> <p>You will also be able to <code>Pause</code> it and restart from the beginning by pressing <code>Reset</code> button which deletes all indexed files from the database.</p> <p>If you change the configuration while file indexing is running, you might need to reset in order to include newly impacted files.</p> <p>File indexing runs every 5 minutes to index last uploaded files.</p> <p></p>"},{"location":"administration/introduction/","title":"Introduction","text":"<p>This guide aims to give you a full overview of the OpenCTI features and workflows. The platform can be used in various contexts to handle threats management use cases from a technical to a more strategic level.</p>"},{"location":"administration/introduction/#administrative-settings","title":"Administrative Settings","text":"<p>The OpenCTI Administrative settings console allows administrators to configure many options dynamically within the system. As an Administrator, you can access this settings console, by clicking the settings link. </p> <p>The Settings Console allows for configuration of various aspects of the system.</p>"},{"location":"administration/introduction/#general-configuration","title":"General Configuration","text":"<ul> <li>Platform Title (Default: OpenCTI - Cyber Threat Intelligence Platform)</li> <li>Platform Favicon</li> <li>Platform General Sender email (Default: admin@opencti.io) </li> <li>Platform Default Theme (Default: Dark)</li> <li>Language (Default: Automatic Detection)</li> <li>Hidden Entity Types (Default: None)</li> </ul>"},{"location":"administration/introduction/#authentication-strategies-display","title":"Authentication Strategies Display","text":"<ul> <li>This section will show configured and enabled/disabled strategies. The configuration is done in the config/default.json file or via ENV variables detected at launch.</li> </ul>"},{"location":"administration/introduction/#platform-messages","title":"Platform Messages","text":"<ul> <li>Platform Login Message (optional) - if configured this will be displayed on the login page. This is usually used to have a welcome type message for users before login.</li> <li>Platform Consent Message (optional) - if configured this will be displayed on the login page. This is usually used to display some type of consent message for users to agree to before login. If enabled, a user must check the checkbox displayed to allow login.</li> <li>Platform Consent Confirm Text (optional) - This is displayed next to the platform consent checkbox, if Platform Consent Message is configured. Users must agree to the checkbox before the login prompt will be displayed. This message can be configured, but by default reads: I have read and comply with the above statement</li> </ul>"},{"location":"administration/introduction/#dark-theme-color-scheme","title":"Dark Theme Color Scheme","text":"<p>Various aspects of the Dark Theme can be dynamically configured in this section.</p>"},{"location":"administration/introduction/#light-theme-color-scheme","title":"Light Theme Color Scheme","text":"<p>Various aspects of the Light Theme can be dynamically configured in this section.</p>"},{"location":"administration/introduction/#tools-configuration-display","title":"Tools Configuration Display","text":"<p>This section will give general status on the various tools and enabled components of the currently configured OpenCTI deployment.</p>"},{"location":"administration/merging/","title":"Merging","text":""},{"location":"administration/merging/#data-merging","title":"Data merging","text":"<p>Within the OpenCTI platform, the merge capability is present into the \"Data &gt; Entities\" tab, and is fairly straightforward to use. To execute a merge, select the set of entities to be merged, then click on the Merge icon.</p> <p>Merging limitation</p> <p>It is not possible to merge entities of different types, nor is it possible to merge more than 4 entities at a time (it will have to be done in several stages).</p> <p></p> <p>Central to the merging process is the selection of a main entity. This primary entity becomes the anchor, retaining crucial attributes such as name and description. Other entities, while losing specific fields like descriptions, are aliased under the primary entity. This strategic decision preserves vital data while eliminating redundancy.</p> <p></p> <p>Once the choice has been made, simply validate to run the task in the background. Depending on the number of entity relationships, and the current workload on the platform, the merge may take more or less time. In the case of a healthy platform and around a hundred relationships per entity, merge is almost instantaneous.</p>"},{"location":"administration/merging/#data-preservation-and-relationship-continuity","title":"Data preservation and relationship continuity","text":"<p>A common concern when merging entities lies in the potential loss of information. In the context of OpenCTI, this worry is alleviated. Even if the merged entities were initially created by distinct sources, the platform ensures that data is not lost. Upon merging, the platform automatically generates relationships directly on the merged entity. This strategic approach ensures that all connections, regardless of their origin, are anchored to the consolidated entity. Post-merge, OpenCTI treats these once-separate entities as a singular, unified entity. Subsequent information from varied sources is channeled directly into the entity resulting from the merger. This unified entity becomes the focal point for all future relationships, ensuring the continuity of data and relationships without any loss or fragmentation.</p>"},{"location":"administration/merging/#important-considerations","title":"Important considerations","text":"<ul> <li>Irreversible process: It's essential to know that a merge operation is irreversible. Once completed, the merged entities cannot be reverted to their original state. Consequently, careful consideration and validation are crucial before initiating the merge process.</li> <li>Loss of fields in aliased entities: Fields, such as descriptions, in aliased entities - entities that have not been chosen as the main - will be lost during the merge. Ensuring that essential information is captured in the primary entity is crucial to prevent data loss.</li> </ul>"},{"location":"administration/merging/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To understand the benefits of entity merger, refer to the Merge objects page in the User Guide section of the documentation.</li> <li>Deduplication mechanism: the platform is equipped with deduplication processes that automatically merge data at creation (either manually or by importing data from different sources) if it meets certain conditions.</li> </ul>"},{"location":"administration/notifier-samples/","title":"Notifier samples","text":""},{"location":"administration/notifier-samples/#configure-teams-webhook","title":"Configure Teams webhook","text":"<p>To configure a notifier for Teams, allowing to send notifications via Teams messages, we followed the guidelines outlined in the Microsoft documentation.</p> <p></p>"},{"location":"administration/notifier-samples/#template-message-for-live-trigger","title":"Template message for live trigger","text":"<p>The Teams template message sent through webhook for a live notification is:</p> <pre><code>{\n        \"type\": \"message\",\n        \"attachments\": [\n            {\n                \"contentType\": \"application/vnd.microsoft.card.thumbnail\",\n                \"content\": {\n                    \"subtitle\": \"Operation : &lt;%=content[0].events[0].operation%&gt;\",\n                    \"text\": \"&lt;%=(new Date(notification.created)).toLocaleString()%&gt;\",\n                    \"title\": \"&lt;%=content[0].events[0].message%&gt;\",\n                    \"buttons\": [\n                        {\n                            \"type\": \"openUrl\",\n                            \"title\": \"See in OpenCTI\",\n                            \"value\": \"https://YOUR_OPENCTI_URL/dashboard/id/&lt;%=content[0].events[0].instance_id%&gt;\"\n                        }\n                    ]\n                }\n            }\n        ]\n    }\n</code></pre>"},{"location":"administration/notifier-samples/#template-message-for-digest","title":"Template message for digest","text":"<p>The Teams template message sent through webhook for a digest notification is:</p> <pre><code>{\n    \"type\": \"message\",\n    \"attachments\": [\n        {\n            \"contentType\": \"application/vnd.microsoft.card.adaptive\",\n            \"content\": {\n                \"$schema\": \"http://adaptivecards.io/schemas/adaptive-card.json\",\n                \"type\": \"AdaptiveCard\",\n                \"version\": \"1.0\",\n                \"body\": [\n                    {\n                        \"type\": \"Container\",\n                        \"items\": [\n                            {\n                                \"type\": \"TextBlock\",\n                                \"text\": \"&lt;%=notification.name%&gt;\",\n                                \"weight\": \"bolder\",\n                                \"size\": \"extraLarge\"\n                            }, {\n                                \"type\": \"TextBlock\",\n                                \"text\": \"&lt;%=(new Date(notification.created)).toLocaleString()%&gt;\",\n                                \"size\": \"medium\"\n                            }\n                        ]\n                    },\n                    &lt;% for(var i=0; i&lt;content.length; i++) { %&gt;\n                    {\n                        \"type\": \"Container\",\n                        \"items\": [&lt;% for(var j=0; j&lt;content[i].events.length; j++) { %&gt;\n                            {\n                                \"type\" : \"TextBlock\",\n                                \"text\" : \"[&lt;%=content[i].events[j].message%&gt;](https://YOUR_OPENCTI_URL/dashboard/id/&lt;%=content[i].events[j].instance_id%&gt;)\"\n                            }&lt;% if(j&lt;(content[i].events.length - 1)) {%&gt;,&lt;% } %&gt;\n                        &lt;% } %&gt;]\n           }&lt;% if(i&lt;(content.length - 1)) {%&gt;,&lt;% } %&gt;\n                    &lt;% } %&gt;\n                ]\n            }\n        }\n    ],\n   \"dataString\": &lt;%-JSON.stringify(notification)%&gt;\n}\n</code></pre>"},{"location":"administration/notifiers/","title":"Custom notifiers","text":"<p>Leveraging the platform's built-in connectors, users can create custom notifiers tailored to their unique needs. OpenCTI features three built-in connectors: a webhook connector, a simple mailer connector, and a platform mailer connector. These connectors operate based on registered schemas that describe their interaction methods.</p> <p></p>"},{"location":"administration/notifiers/#built-in-notifier-connectors","title":"Built-In notifier connectors","text":""},{"location":"administration/notifiers/#platform-mailer","title":"Platform mailer","text":"<p>This notifier connector enables customization of notifications raised within the platform. It's simple to configure, requiring only:</p> <ul> <li>Title: The title for the platform notification.</li> <li>Template: Specifies the message template for the notification.</li> </ul>"},{"location":"administration/notifiers/#simple-mailer","title":"Simple mailer","text":"<p>This notifier connector offers a straightforward approach to email notifications with simplified configuration options. Users can set:</p> <ul> <li>Title: The title for the email notification.</li> <li>Header: Additional content to include at the beginning of the email.</li> <li>Footer: Additional content to include at the end of the email.</li> <li>Logo: The option to add a logo to the email.</li> <li>Background Color: Customize the background color of the email.</li> </ul> <p></p>"},{"location":"administration/notifiers/#webhook","title":"Webhook","text":"<p>This notifier connector enables users to send notifications to external applications or services through HTTP requests. Users can specify:</p> <ul> <li>Verb: Specifies the HTTP method (GET, POST, PUT, DELETE).</li> <li>URL: Defines the destination URL for the webhook.</li> <li>Template: Specifies the message template for the notification.</li> <li>Parameters and Headers: Customizable parameters and headers sent through the webhook request.</li> </ul> <p>OpenCTI provides two notifier samples by default, designed to communicate with Microsoft Teams through a webhook. A documentation page providing details on these samples is available.</p>"},{"location":"administration/notifiers/#configuration-and-access","title":"Configuration and access","text":"<p>Custom notifiers are manageable in the \"Settings &gt; Customization &gt; Notifiers\" window and can be restricted through Role-Based Access Control (RBAC). Administrators can control access, limiting usage to specific Users, Groups, or Organizations.</p> <p>For guidance on configuring notification triggers and exploring the usages of notifiers, refer to the dedicated documentation page.</p>"},{"location":"administration/ontologies/","title":"Taxonomies","text":"<p>Taxonomies in OpenCTI refer to the structured classification systems that help in organizing and categorizing cyber threat intelligence data. They play a crucial role in the platform by allowing analysts to systematically tag and retrieve information based on predefined categories and terms.</p> <p>Along with the Customization page, these pages allow the administrator to customize the platform.</p>"},{"location":"administration/ontologies/#labels","title":"Labels","text":"<p>Labels in OpenCTI serve as a powerful tool for organizing, categorizing, and prioritizing data. Here\u2019s how they can be used effectively:</p> <ol> <li>Tagging and Categorization: Labels can be used to tag malware, incidents, or indicators (IOCs) with specific categories, making it easier to filter and search through large datasets.</li> <li>Prioritization: By labeling threats based on their severity or impact, security analysts can prioritize their response efforts accordingly.</li> <li>Correlation and Analysis: Labels help in correlating different pieces of intelligence. For example, if multiple indicators are tagged with the same label, it might indicate a larger campaign or a common adversary.</li> <li>Automation and Integration: Labels can trigger automated workflows (also called playbooks) within OpenCTI. For instance, a label might automatically initiate further investigation or escalate an incident.</li> <li>Reporting and Metrics: Labels facilitate the generation of reports and metrics, allowing organizations to track trends through dashboards, measure response effectiveness, and make data-driven decisions.</li> <li>Sharing and Collaboration: When sharing intelligence with other organizations or platforms, labels provide a common language that helps in understanding the context and relevance of the shared data.</li> </ol> <p>Tip</p> <p>In order to achieve effective data labeling methods, it is recommended to establish a clear and consistent criteria for your labeling and document them in a policy or guideline.</p>"},{"location":"administration/ontologies/#kill-chain-phases","title":"Kill chain phases","text":"<p>Kill chain phases are used in OpenCTI to structure and analyze the data related to cyber threats and attacks. They describe the stages of an attack from the perspective of the attacker and provide a framework for identifying, analysing and responding to threats.</p> <p>OpenCTI supports the following kill chain models:</p> <ul> <li>Lockheed Martin Cyber Kill Chain</li> <li>MITRE ATT&amp;CK Framework (Entreprise, PRE, Mobile and ICS)</li> <li>DISARM framework</li> </ul> <p>You can add, edit, or delete kill chain phases in the settings page, and assign them to indicators, attack patterns, incidents, or courses of action in the platform. You can also filter the data by kill chain phase, and view the kill chain phases in a timeline or as a matrix.</p> <p></p>"},{"location":"administration/ontologies/#vocabularies","title":"Vocabularies","text":"<p>Open vocabularies are sets of terms and definitions that are agreed upon by the CTI community. They help to standardize the communication documentation of cyber threat information. This section allows you to customize a set of available fields by adding vocabulary. Almost all of the drop-down menus available in the entities can be modified from this panel.</p> <p>Open vocabularies in OpenCTI are mainly based on the STIX standard.</p> <p></p>"},{"location":"administration/ontologies/#status-templates","title":"Status templates","text":"<p>Status templates are predefined statuses that can be assigned to different entities in OpenCTI, such as reports, incidents, or cases (incident responses, requests for information and requests for takedown).</p> <p>They help to track the progress of the analysis and response activities by defining statuses that are used in the workflows.</p> <p></p>"},{"location":"administration/ontologies/#case-templates","title":"Case templates","text":"<p>Customizable case templates help to streamline the process of creating cases with predefined lists of tasks.</p> <p></p>"},{"location":"administration/organization-segregation/","title":"Organization segregation","text":"<p>Enterprise edition</p> <p>Platform segregation by organization is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all the information.</p>"},{"location":"administration/organization-segregation/#organization-administration","title":"Organization administration","text":"<p>Platform administrators can promote members of an organization as \"Organization administrator\". This elevated role grants them the necessary capabilities to create, edit and delete users from the corresponding Organization. Additionally, administrators have the flexibility to define a list of groups that can be granted to newly created members by the organization administrators. This feature simplifies the process of granting appropriate access and privileges to individuals joining the organization.</p> <p></p> <p>The platform administrator can promote/demote an organization admin through its user edition form.</p> <p></p> <p>Organization admin rights</p> <p>The \"Organization admin\" has restricted access to Settings. They can only manage the members of the organizations for which they have been promoted as \"admins\".</p>"},{"location":"administration/parameters/","title":"Parameters","text":""},{"location":"administration/parameters/#description","title":"Description","text":"<p>This part of the interface wil let you configure global platform settings, like title, favicon, etc.</p> <p>It will also give you important information about the platform.</p>"},{"location":"administration/parameters/#the-configuration-section","title":"The \"Configuration\" section","text":"<p>This section allows the administrator to edit the following settings:</p> <ul> <li>Platform title</li> <li>Platform favicon URL</li> <li>Sender email address: email address displayed as sender when sending notifications. The technical sender is defined in the SMTP configuration.</li> <li>Theme</li> <li>Language</li> <li>Hidden entity types: allows you to customize which types of entities you want to see or hide in the platform. This can help you focus on the relevant information and avoid cluttering the platform with unnecessary data.</li> </ul>"},{"location":"administration/parameters/#opencti-platform","title":"OpenCTI Platform","text":"<p>This is where the Enterprise edition can be enabled.</p> <p>This section gives important information about the platform like the used version, the edition, the architecture mode (can be Standalone or Cluster) and the number used nodes.</p> <p>Through the \"Remove Filigran logos\" toggle, the administrator has the option to hide the Filigran logo on the login page and the sidebar.</p>"},{"location":"administration/parameters/#platform-announcement","title":"Platform Announcement","text":"<p>This section gives you the possibility to set and display Announcements in the platform. Those announcements will be visible to every user in the platform, on top of the interface.</p> <p>They can be used to inform some of your users or all of important information, like a scheduled downtime, an incoming upgrade, or even to share important tips regarding the usage of the platform.</p> <p>An Announcement can be accompanied by a \"Dismiss\u201d button. When clicked by a user, it makes the message disappear for this user.</p> <p></p> <p>This option can be deactivated to have a permanent announcement.</p> <p> \u26a0\ufe0f Only one announcement is shown at a time, with priority given to dismissible ones. If there are no dismissible announcements, the most recent non-dismissible one is shown.</p>"},{"location":"administration/parameters/#third-party-analytics","title":"Third-party Analytics","text":"<p>Enterprise edition</p> <p>Analytics is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have more information</p> <p>This is where you can configure analytics providers. At the moment only Google Analytics v4 is supported.</p>"},{"location":"administration/parameters/#theme-customization","title":"Theme customization","text":"<p>In this section, the administrator can customize the two OpenCTI themes </p>"},{"location":"administration/parameters/#tools","title":"Tools","text":"<p>This section informs the administrator of the statuses of the different managers used in the Platform. More information about the managers can be found here. It shows also the used versions of the search engine database, RabbitMQ and Redis.</p> <p>In cluster mode, the fact that a manager appears as enabled means that it is active in at least one node. </p> <p></p>"},{"location":"administration/policies/","title":"Policies","text":"<p>The Policies configuration window (in \"Settings &gt; Security &gt; Policies\") encompasses essential settings that govern the organizational sharing, authentication strategies, password policies, login messages, and banner appearance within the OpenCTI platform.</p>"},{"location":"administration/policies/#platform-main-organization","title":"Platform main organization","text":"<p>Allow to set a main organization for the entire platform. Users belonging to the main organization enjoy unrestricted access to all data stored in the platform. In contrast, users affiliated with other organizations will only have visibility into data explicitly shared with them.</p> <p></p> <p>Numerous repercussions linked to the activation of this feature</p> <p>This feature has implications for the entire platform and must be fully understood before being used. For example, it's mandatory to have organizations set up for each user, otherwise they won't be able to log in. It is also advisable to include connector's users in the platform main organization to avoid import problems.</p>"},{"location":"administration/policies/#authentication-strategies","title":"Authentication strategies","text":"<p>The authentication strategies section provides insights into the configured authentication methods. Additionally, an \"Enforce Two-Factor Authentication\" button is available, allowing administrators to mandate 2FA activation for users, enhancing overall account security.</p> <p>Please see the Authentication section for further details on available authentication strategies.</p> <p></p>"},{"location":"administration/policies/#local-password-policies","title":"Local password policies","text":"<p>This section encompasses a comprehensive set of parameters defining the local password policy. Administrators can specify requirements such as minimum/maximum number of characters, symbols, digits, and more to ensure robust password security across the platform. Here are all the parameters available:</p> Parameter Description <code>Number of chars must be greater than or equals to</code> Define the minimum length required for passwords. <code>Number of chars must be lower or equals to (0 equals no maximum)</code> Set an upper limit for password length. <code>Number of symbols must be greater or equals to</code> Specify the minimum number of symbols required in a password. <code>Number of digits must be greater or equals to</code> Set the minimum number of numeric characters in a password. <code>Number of words (split on hyphen, space) must be greater or equals to</code> Enforce a minimum count of words in a password. <code>Number of lowercase chars must be greater or equals to</code> Specify the minimum number of lowercase characters. <code>Number of uppercase chars must be greater or equals to</code> Specify the minimum number of uppercase characters. <p></p>"},{"location":"administration/policies/#login-messages","title":"Login messages","text":"<p>Allow to define messages on the login page to customize and highlight your platform's security policy. Three distinct messages can be customized:</p> <ul> <li>Platform login message: Appears above the login form to convey important information or announcements.</li> <li>Platform consent message: A consent message that obscures the login form until users check the approval box, ensuring informed user consent.</li> <li>Platform consent confirm text: A message accompanying the consent box, providing clarity on the consent confirmation process.</li> </ul> <p></p> <p></p>"},{"location":"administration/policies/#platform-banner-configuration","title":"Platform banner configuration","text":"<p>The platform banner configuration section allows administrators to display a custom banner message at the top and bottom of the screen. This feature enables customization for enhanced visual communication and branding within the OpenCTI platform. It can be used to add a disclaimer or system purpose.</p> <p>This configuration has two parameters:</p> <ul> <li>Platform banner level: Options defining the banner background color (Green, Red, or Yellow).</li> <li>Platform banner text: Field referencing the message to be displayed within the banner.</li> </ul> <p></p>"},{"location":"administration/policies/#maximum-marking-definitions-shareable","title":"Maximum marking definitions shareable","text":"<p>This configuration allows to define, for each type of marking definitions, until which level we allow to share data externally.</p> <p>For now this max marking definitions is used only for Public dashboard.</p> <p>For example in the capture below, for the type of marking <code>TLP</code>, only data  with a marking definition with a level equal or below <code>GREEN</code> will be shareable through Public Dashboard. And no data with marking definition <code>statement</code> will be shared at all.</p> <p></p>"},{"location":"administration/reasoning/","title":"Rules engine","text":""},{"location":"administration/reasoning/#inference-rules","title":"Inference rules","text":"<p>The rules engine comprises a set of predefined rules (named inference rules) that govern how new relationships are inferred based on existing data. These rules are carefully crafted to ensure logical and accurate relationship creation. Here is the list of existing inference rules:</p>"},{"location":"administration/reasoning/#raise-incident-based-on-sighting","title":"Raise incident based on sighting","text":"Conditions Creations A non-revoked Indicator is sighted in an Entity Creation of an Incident linked to the sighted Indicator and the targeted Entity"},{"location":"administration/reasoning/#sightings-of-observables-via-observed-data","title":"Sightings of observables via observed data","text":"Conditions Creations An Indicator is based on an Observable contained in an Observed Data Creation of a sighting between the Indicator and the creating Identity of the Observed Data"},{"location":"administration/reasoning/#sightings-propagation-from-indicator","title":"Sightings propagation from indicator","text":"Conditions Creations An Indicator based on an Observable is sighted in an Entity The Observable is sighted in the Entity"},{"location":"administration/reasoning/#sightings-propagation-from-observable","title":"Sightings propagation from observable","text":"Conditions Creations An Indicator is based on an Observable sighted in an Entity The Indicator is sighted in the Entity"},{"location":"administration/reasoning/#relation-propagation-via-an-observable","title":"Relation propagation via an observable","text":"Conditions Creations An observable is related to two Entities Create a related to relationship between the two Entities"},{"location":"administration/reasoning/#attribution-propagation","title":"Attribution propagation","text":"Conditions Creations An Entity A is attributed to an Entity B and this Entity B is itself attributed to an Entity C The Entity A is attributed to Entity C"},{"location":"administration/reasoning/#belonging-propagation","title":"Belonging propagation","text":"Conditions Creations An Entity A is part of an Entity B and this Entity B is itself part of an Entity C The Entity A is part of Entity C"},{"location":"administration/reasoning/#location-propagation","title":"Location propagation","text":"Conditions Creations A Location A is located at a Location B and this Location B is itself located at a Location C The Location A is located at Location C"},{"location":"administration/reasoning/#organization-propagation-via-participation","title":"Organization propagation via participation","text":"Conditions Creations A User is affiliated with an Organization B, which is part of an Organization C The User is affiliated to the Organization C"},{"location":"administration/reasoning/#identities-propagation-in-reports","title":"Identities propagation in reports","text":"Conditions Creations A Report contains an Identity B and this Identity B is part of an Identity C The Report contains Identity C, as well as the Relationship between Identity B and Identity C"},{"location":"administration/reasoning/#locations-propagation-in-reports","title":"Locations propagation in reports","text":"Conditions Creations A Report contains a Location B and this Location B is located at a Location C The Report contains Location B, as well as the Relationship between Location B and Location C"},{"location":"administration/reasoning/#observables-propagation-in-reports","title":"Observables propagation in reports","text":"Conditions Creations A Report contains an Indicator and this Indicator is based on an Observable The Report contains the Observable, as well as the Relationship between the Indicator and the Observable"},{"location":"administration/reasoning/#usage-propagation-via-attribution","title":"Usage propagation via attribution","text":"Conditions Creations An Entity A, attributed to an Entity C, uses an Entity B The Entity C uses the Entity B"},{"location":"administration/reasoning/#inference-of-targeting-via-a-sighting","title":"Inference of targeting via a sighting","text":"Conditions Creations An Indicator, sighted at an Entity C, indicates an Entity B The Entity B targets the Entity C"},{"location":"administration/reasoning/#targeting-propagation-via-attribution","title":"Targeting propagation via attribution","text":"Conditions Creations An Entity A, attributed to an Entity C, targets an Entity B The Entity C targets the Entity B"},{"location":"administration/reasoning/#targeting-propagation-via-belonging","title":"Targeting propagation via belonging","text":"Conditions Creations An Entity A targets an Identity B, part of an Identity C The Entity A targets the Identity C"},{"location":"administration/reasoning/#targeting-propagation-via-location","title":"Targeting propagation via location","text":"Conditions Creations An Entity targets a Location B and this Location B is located at a Location C The Entity targets the Location C"},{"location":"administration/reasoning/#targeting-propagation-when-located","title":"Targeting propagation when located","text":"Conditions Creations An Entity A targets an Entity B and this target is located at Location D. The Entity A targets the Location D"},{"location":"administration/reasoning/#rule-execution","title":"Rule execution","text":""},{"location":"administration/reasoning/#rule-activation","title":"Rule activation","text":"<p>When a rule is activated, a background task is initiated. This task scans all platform data, identifying existing relationships that meet the conditions defined by the rule. Subsequently, it creates new objects (entities and/or relationships), expanding the network of insights within your threat intelligence environment. Then, activated rules operate continuously. Whenever a relationship is created or modified, and this change aligns with the conditions specified in an active rule, the reasoning mechanism is triggered. This ensures real-time relationship inference.</p>"},{"location":"administration/reasoning/#rule-deactivation","title":"Rule deactivation","text":"<p>Deactivating a rule leads to the deletion of all objects and relationships created by it. This cleanup process maintains the accuracy and reliability of your threat intelligence database.</p>"},{"location":"administration/reasoning/#access-restrictions-and-data-impact","title":"Access restrictions and data impact","text":"<p>Access to the rule engine panel is restricted to administrators only. Regular users do not have visibility into this section of the platform. Administrators possess the authority to activate or deactivate rules.</p> <p>The rules engine empowers OpenCTI with the capability to automatically establish intricate relationships within your data. However, these rules can lead to a very large number of objects created. Even if the operation is reversible, an administrator should consider the impact of activating a rule.</p>"},{"location":"administration/reasoning/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To understand the benefits and results of these rules, refer to the Inferences and reasoning page in the User Guide section of the documentation.</li> <li>New inference rule: Given the potential impact of a rule on your data, users are not allowed to add new rules. However, users can submit rule suggestions via a GitHub issue for evaluation. These suggestions are carefully evaluated by our team, ensuring continuous improvement and innovation.</li> </ul>"},{"location":"administration/retentions/","title":"Retention policies","text":"<p>Retention rules serve the purpose of establishing data retention times, specifying when data should be automatically deleted from the platform. Users can define filters to target specific objects. Any object meeting these criteria that haven't been updated within the designated time frame will be permanently deleted.</p> <p>Note that the data deleted by an active retention policy will not appear in the trash and thus cannot be restored.  </p>"},{"location":"administration/retentions/#configuration","title":"Configuration","text":"<p>Retention rules can be configured in the \"Settings &gt; Customization &gt; Retention policies\" window. A set of parameters must be configured:</p> <ul> <li>Maximum retention days: Set the maximum number of days an object can remain unchanged before being eligible for deletion.</li> <li>Filters: Define filters based on specific criteria to select the types of objects subject to retention rules.</li> </ul> <p>An object will be removed if it meets the specified filters and hasn't been updated for the duration set in the \"Maximum retention days\" field.</p> <p></p>"},{"location":"administration/retentions/#verification-process","title":"Verification process","text":"<p>Before activating a retention rule, users have the option to verify its impact using the \"Verify\" button. This action provides insight into the number of objects that currently match the rule's criteria and would be deleted if the rule is activated.</p> <p></p> <p>Verify before activation</p> <p>Always use the \"Verify\" feature to assess the potential impact of a retention rule before activating it. Once the rule is activated, data deletion will begin, and retrieval of the deleted data will not be possible.</p> <p>Retention rules contribute to maintaining a streamlined and efficient data lifecycle within OpenCTI, ensuring that outdated or irrelevant information is systematically removed from the platform, thereby optimizing disk space usage.</p>"},{"location":"administration/segregation/","title":"Marking restriction","text":"<p>Data segregation in the context of Cyber Threat Intelligence refers to the practice of categorizing and separating different types of data or information related to cybersecurity threats based on specific criteria.</p> <p>This separation helps organizations manage and analyze threat intelligence more effectively and securely and the goal of data segregation is to ensure that only those individuals who are authorized to view a particular set of data have access to that set of data.</p> <p>Practically, \"Need-to-know basis\" and \"classification level\" are data segregation measures.</p>"},{"location":"administration/segregation/#description","title":"Description","text":"<p>Marking definitions are essential in the context of data segregation to ensure that data is appropriately categorized and protected based on its sensitivity or classification level. Marking definitions establish a standardized framework for classifying data.</p> <p>Marking Definition objects are unique among STIX objects in the STIX 2.1 standard in that they cannot be versioned. This restriction is in place to prevent the possibility of indirect alterations to the markings associated with a STIX Object.</p> <p>Multiple markings can be added to the same object. Certain categories of marking definitions or trust groups may enforce rules that specify which markings take precedence over others or how some markings can be added to complement existing ones.</p> <p>In OpenCTI, data is segregated based on knowledge marking. The diagram provided below illustrates the manner in which OpenCTI establishes connections between pieces of information to authorize data access for a user:</p> <p></p>"},{"location":"administration/segregation/#manage-markings","title":"Manage markings","text":""},{"location":"administration/segregation/#create-new-markings","title":"Create new markings","text":"<p>To create a marking, you must first possess the capability <code>Manage marking definitions</code>. For further information on user administration, please refer to the Users and Role Based Access Control page.</p> <p>Once you have access to the settings, navigate to \"Settings &gt; Security &gt; Marking Definitions\" to create a new marking.</p> <p>A marking consists of the following attributes:</p> <ul> <li>Type: Specifies the marking group to which it belongs.</li> <li>Definition: The name assigned to the marking.</li> <li>Color: The color associated with the marking.</li> <li>Order: Determines the hierarchical order among markings of the same type.</li> </ul> <p></p>"},{"location":"administration/segregation/#allowed-marking","title":"Allowed marking","text":"<p>The configuration of authorized markings for a user is determined at the Group level. To access entities and relationships associated with specific markings, the user must belong to a group that has been granted access to those markings.</p> <p>There are two ways in which markings can be accessed:</p> <ul> <li>The user is a member of a group that has been granted access to the marking.</li> <li>The user is a member of a group that has access to a marking of the same type, with an equal or higher hierarchical order.</li> </ul> <p>Access to an object with several markings</p> <p>Access to all markings attached to an object is required in order to access it (not only one).</p> <p>Automatically grant access to the new marking</p> <p>To allow a group to automatically access a newly created marking definition, you can check <code>Automatically authorize this group to new marking definition</code>.</p>"},{"location":"administration/segregation/#default-marking-definitions","title":"Default marking definitions","text":"<p>To apply a default marking when creating a new entity or relationship, you can choose which marking to add by default from the list of allowed markings. You can add only one marking per type, but you can have multiple types. This configuration is also done at the Group level.</p> <p></p> <p>Need a configuration change</p> <p>Simply adding markings as default markings is insufficient to display the markings when creating an entity or relationship. You also need to enable default markings in the customization settings of an entity or relationship. For example, to enable default markings for a new report, navigate to \"Settings &gt; Customization &gt; Report &gt; Markings\" and toggle the option to <code>Activate/Desactivate default values</code>.</p>"},{"location":"administration/segregation/#management-of-multiple-markings","title":"Management of multiple markings","text":"<p>In scenarios where multiple markings of the same type but different orders are added, the platform will retain only the marking with the highest order for each type. This consolidation can occurs in various instances:</p> <ul> <li>During entity creation, if multiple markings are selected.</li> <li>During entity updates, whether manually or via a connector, if additional markings are introduced.</li> <li>When multiple entities are merged, their respective markings will be amalgamated.</li> </ul> <p>For example:</p> <p>Create a new report and add markings <code>PAP:AMBER</code>,<code>PAP:RED</code>,<code>TLP:AMBER+STRICT</code>,<code>TLP:CLEAR</code> and a statement <code>CC-BY-SA-4.0 DISARM Foundation</code></p> <p></p> <p>The final markings kept are: <code>PAP:RED</code>, <code>TLP:AMBER+STRICT</code> and <code>CC-BY-SA-4.0 DISARM Foundation</code></p> <p></p>"},{"location":"administration/segregation/#update-an-object-manually","title":"Update an object manually","text":"<p>When update an entity or a relationship:</p> <ul> <li>add a marking with the same type and different orders, a pop-up will be displayed to confirm the choice,</li> <li>add a marking with the same type and the same order, the marking will be added,</li> <li>add a marking with different types, the marking will be added.</li> </ul> <p></p>"},{"location":"administration/segregation/#import-data-from-a-connector","title":"Import data from a connector","text":"<p>As a result of this mechanism, when importing data from a connector, the connector is unable to downgrade a marking for an entity if a marking of the same type is already present on it.</p>"},{"location":"administration/segregation/#additional-information","title":"Additional information","text":"<p>The Traffic Light Protocol is implemented by default as marking definitions in OpenCTI. It allows you to segregate information by TLP levels in your platform and restrict access to marked data if users are not authorized to see the corresponding marking.</p> <p>The Traffic Light Protocol (TLP) was designed by the Forum of Incident Response and Security Teams (FIRST) to provide a standardized method for classifying and handling sensitive information, based on four categories of sensitivity.</p> <p>For more details, the diagram provided below illustrates how are categorized the marking definitions:</p> <p></p>"},{"location":"administration/support-package/","title":"Support Package","text":"<p>Support packages are useful for troubleshooting issue that occurs on OpenCTI platform. Administrators can request to create and download a support package that contains recent platform error logs and usage statistics.</p> <p>Support package content</p> <p>Even if we do our best to prevent logging any data, the support package may contains some sensitive information that you may not want to share with everyone. Before creating a ticket with your support package takes some time to check if you can safely share the content depending of your security policy.</p> <p>Support Package can be requested from \"Settings &gt; Support\" menu.</p> <p></p>"},{"location":"administration/support-package/#package-generation","title":"Package generation","text":"<p>On a click on \"Generate support package\", a support event is propagated to every platform instances to request needed information. Every instance that will receive this message will process the request and send the files to the platform. During this processing the interface will display the expected support package name in an IN PROGRESS state waiting for completion. After finishing the process the support package will move to the READY state and the buttons download and delete will be activated.</p>"},{"location":"administration/support-package/#package-download","title":"Package download","text":"<p>After file generation, using the download button will dynamically create a (zip) containing all instances logs and telemetry.</p>"},{"location":"administration/support-package/#partial-package","title":"Partial package","text":"<p>In case of platform instability, some logs might not be retrieved and the support package will be incomplete.</p> <p>If some instances fail to send their data, you will be able to force download a partial zip only after 1 minute. In case of a support package taking more than 5 minutes, the status will be moved to \"timeout\".</p>"},{"location":"administration/users/","title":"Users and Role Based Access Control","text":""},{"location":"administration/users/#introduction","title":"Introduction","text":"<p>In OpenCTI, the RBAC system not only related to what users can do or cannot do in the platform (aka. <code>Capabilities</code>) but also to the system of data segregation. Also, platform behavior such as default home dashboards, default triggers and digests as well as default hidden menus or entities can be defined across groups and organizations.</p>"},{"location":"administration/users/#high-level-design","title":"High level design","text":""},{"location":"administration/users/#roles","title":"Roles","text":"<p>Roles are used in the platform to grant the given groups with some capabilities to define what users in those groups can do or cannot do.</p>"},{"location":"administration/users/#list-of-capabilities","title":"List of capabilities","text":"Capability Description <code>Bypass all capabilities</code> Just bypass everything including data segregation and enforcements. <code>Access knowledge</code> Access in read-only to all the knowledge in the platform. <code>Access to collaborative creation</code> Create notes and opinions (and modify its own) on entities and relations. <code>Create / Update knowledge</code> Create and update existing entities and relationships. <code>Restrict organization access</code> Share entities and relationships with other organizations. <code>Delete knowledge</code> Delete entities and relationships. <code>Upload knowledge files</code> Upload files in the <code>Data</code> and <code>Content</code> section of entities. <code>Download knowledge export</code> Download the exports generated in the entities (in the <code>Data</code> section). <code>Ask for knowledge enrichment</code> Trigger an enrichment for a given entity. <code>Access Dashboards and investigations</code> Access to existing custom dashboards and investigations. <code>Create / Update Dashboards and investigations</code> Create and update custom dashboards and investigations. <code>Delete Dashboards and investigations</code> Delete existing custom dashboards and investigations. <code>Manage Public Dashboards</code> Manage public dashboards <code>Access connectors</code> Read information in the <code>Data &gt; Connectors</code> section. <code>Manage connector state</code> Reset the connector state to restart ingestion from the beginning. <code>Access data sharing &amp; ingestion</code> Access and consume data such as TAXII collections. <code>Manage data sharing &amp; ingestion</code> Share data such as TAXII collections or custom dashboards. <code>Manage CSV mappers</code> Create, update and delete CSV mappers. <code>Access administration</code> Access and manage overall parameters of the platform in <code>Settings &gt; Parameters</code>. <code>Manage credentials</code> Access and manage roles, groups, users, organizations and security policies. <code>Manage marking definitions</code> Update and delete marking definitions. <code>Manage labels &amp; Attributes</code> Update and delete labels, custom taxonomies, workflow and case templates. <code>Connectors API usage: register, ping, export push ...</code> Connectors specific permissions for register, ping, push export files, etc. <code>Connect and consume the platform streams (/stream, /stream/live)</code> List and consume the OpenCTI live streams. <code>Bypass mandatory references if any</code> If external references enforced in a type of entity, be able to bypass the enforcement."},{"location":"administration/users/#manage-roles","title":"Manage roles","text":"<p>You can manage the roles in <code>Settings &gt; Security &gt; Roles</code>.</p> <p>To create a role, just click on the <code>+</code> button:</p> <p></p> <p>Then you will be able to define the capabilities of the role:</p> <p></p>"},{"location":"administration/users/#users","title":"Users","text":"<p>You can manage the users in <code>Settings &gt; Security &gt; Users</code>. If you are using Single-Sign-On (SSO), the users in OpenCTI are automatically created upon login.</p> <p>To create a user, just click on the <code>+</code> button:</p> <p></p>"},{"location":"administration/users/#manage-a-user","title":"Manage a user","text":"<p>When access to a user, it is possible to:</p> <ul> <li>Visualize information including the token</li> <li>Modify it, reset 2FA if necessary</li> <li>Manage its sessions</li> <li>Manage its triggers and digests</li> <li>Visualize the history and operations</li> <li>Manage its max confidence level (override the value inherited from the group)</li> </ul> <p></p> <p>In the image below, you can see how to override the value inherited from the group.</p> <p></p> <p>Mandatory max confidence level</p> <p>A user without Max confidence level won't have the ability to create, delete or update any data in our platform. Please be sure that your users are always either assigned to group that have a confidence level defined or that have an override of this group confidence level.</p> <p></p>"},{"location":"administration/users/#groups","title":"Groups","text":"<p>Groups are the main way to manage permissions and data segregation as well as platform customization for the given users part of this group. You can manage the groups in <code>Settings &gt; Security &gt; Groups</code>.</p> <p>Here is the description of the group available parameters.</p> Parameter Description <code>Auto new markings</code> If a new marking definition is created, this group will automatically be granted to it. <code>Default membership</code> If a new user is created (manually or upon SSO), it will be added to this group. <code>Roles</code> Roles and capabilities granted to the users belonging to this group. <code>Default dashboard</code> Customize the home dashboard for the users belonging to this group. <code>Default markings</code> In <code>Settings &gt; Customization &gt; Entity types</code>, if a default marking definition is enabled, default markings of the group is used. <code>Allowed markings</code> Grant access to the group to the defined marking definitions, more details in data segregation. <code>Triggers and digests</code> Define defaults triggers and digests for the users belonging to this group. <code>Max confidence level</code> Define the maximum confidence level for the group: it will impact the capacity to update entities, the confidence level of a newly created entity by a user of the group. <p></p> <p>Max confidence level when a user has multiple groups</p> <p>A user with multiple groups will have the the highest confidence level of all its groups.  For instance, if a user is part of group A (max confidence level = 100) and group B (max confidence level = 50), then the user max confidence level will be 100.</p>"},{"location":"administration/users/#manage-a-group","title":"Manage a group","text":"<p>When managing a group, you can define the members and all above configurations.</p> <p></p> <p></p>"},{"location":"administration/users/#organizations","title":"Organizations","text":"<p>Users can belong to organizations, which is an additional layer of data segregation and customization. To find out more about this part, please refer to the page on organization segregation.</p>"},{"location":"administration/users/#organization-administration","title":"Organization administration","text":"<p>Platform administrators can promote members of an organization as \"Organization administrator\". This elevated role grants them the necessary capabilities to create, edit and delete users from the corresponding Organization. Additionally, administrators have the flexibility to define a list of groups that can be granted to newly created members by the organization administrators. This feature simplifies the process of granting appropriate access and privileges to individuals joining the organization.</p> <p></p> <p>The platform administrator can promote/demote an organization admin through its user edition form.</p> <p></p> <p>Organization admin rights</p> <p>The \"Organization admin\" has restricted access to Settings. They can only manage the members of the organizations for which they have been promoted as \"admins\".</p>"},{"location":"administration/audit/configuration/","title":"Configuration","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p> <p>As explained in the overview page, all administration actions are listened by default.  However, all knowledge are not listened by default due to performance impact on the platform. </p> <p>For this reason you need to explicitly activate extended listening on user / group or organization.</p> <p></p> <p>Listening will start just after the configuration. Every past events will not be taken into account.</p>"},{"location":"administration/audit/events/","title":"Events","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/audit/events/#description","title":"Description","text":"<p>OpenCTI activity capability is the way to unified whats really happen in the platform. In events section you will have access to the UI that will answer to \"who did what, where, and when?\" within your data with the maximum level of transparency. </p> <p></p>"},{"location":"administration/audit/events/#include-knowledge","title":"Include knowledge","text":"<p>By default, the events screen only show you the administration actions done by the users.</p> <p>If you want to see also the information about the knowledge, you can simply activate the filter in the bar to get the complete overview of all user actions.</p> <p>Don't hesitate to read again the overview page to have a better understanding of the difference between Audit, Basic/Extended knowledge.</p>"},{"location":"administration/audit/overview/","title":"Overview","text":""},{"location":"administration/audit/overview/#overview","title":"Overview","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all the information</p> <p>OpenCTI activity capability is the way to unify what's really happening in the platform. With this feature you will be able to answer \"who did what, where, and when?\" within your data with the maximum level of transparency. </p> <p>Enabling activity helps your security, auditing, and compliance entities monitor platform for possible vulnerabilities or external data misuse.</p>"},{"location":"administration/audit/overview/#categories","title":"Categories","text":"<p>The activity groups 3 different concepts that need to be explained.</p>"},{"location":"administration/audit/overview/#basic-knowledge","title":"Basic knowledge","text":"<p>The basic knowledge refers to all STIX data knowledge inside OpenCTI. Every create/update/delete action on that knowledge is accessible through the history. That basic activity is handled by the history manager and can also be found directly on each entity.</p>"},{"location":"administration/audit/overview/#extended-knowledge","title":"Extended knowledge","text":"<p>The extended knowledge refers to extra information data to track specific user activity. As this kind of tracking is expensive, the tracking will only be done for specific users/groups/organizations explicitly configured in the configuration window.</p>"},{"location":"administration/audit/overview/#audit-knowledge","title":"Audit knowledge","text":"<p>Audit is focusing on user administration or security actions. Audit will produce console/logs files along with user interface elements.</p> <pre><code>{\n  \"auth\": \"&lt;User information&gt;\",\n  \"category\": \"AUDIT\",\n  \"level\": \"&lt;info | error&gt;\",\n  \"message\": \"&lt;human readable explanation&gt;\",\n  \"resource\": {\n    \"type\": \"&lt;authentication | mutation&gt;\",\n    \"event_scope\": \"&lt;depends on type&gt;\",\n    \"event_access\": \"&lt;administration&gt;\",\n    \"data\": \"&lt;contextual data linked to the event type&gt;\",\n    \"version\": \"&lt;version of audit log format&gt;\"\n  },\n  \"timestamp\": \"&lt;event date&gt;\",\n  \"version\": \"&lt;platform version&gt;\"\n}\n</code></pre>"},{"location":"administration/audit/overview/#architecture","title":"Architecture","text":"<p>OpenCTI uses different mechanisms to be able to publish actions (audit) or data modification (history)</p>"},{"location":"administration/audit/overview/#audit-knowledge_1","title":"Audit knowledge","text":"<p>Administration or security actions</p> <p>With Enterprise edition activated, Administration and security actions are always written; you can't configure, exclude, or disable them</p> <p> Supported</p> <p> Not supported for now</p> <p> Not applicable</p>"},{"location":"administration/audit/overview/#ingestion","title":"Ingestion","text":"Create Delete Edit Remote OCTI Streams"},{"location":"administration/audit/overview/#data-sharing","title":"Data sharing","text":"Create Delete Edit CSV Feeds TAXII Feeds Stream Feeds"},{"location":"administration/audit/overview/#connectors","title":"Connectors","text":"Create Delete Edit Connectors  State reset Works"},{"location":"administration/audit/overview/#parameters","title":"Parameters","text":"Create Delete Edit Platform parameters"},{"location":"administration/audit/overview/#security","title":"Security","text":"Create Delete Edit Roles Groups Users Sessions Policies"},{"location":"administration/audit/overview/#customization","title":"Customization","text":"Create Delete Edit Entity types Rules engine Retention policies"},{"location":"administration/audit/overview/#taxonomies","title":"Taxonomies","text":"Create Delete Edit Status templates Case templates + tasks"},{"location":"administration/audit/overview/#accesses","title":"Accesses","text":"Listen Login (success or fail) Logout Unauthorized access"},{"location":"administration/audit/overview/#extended-knowledge_1","title":"Extended knowledge","text":"<p>Extended knowledge</p> <p>Extented knowledge activity are written only if you activate the feature for a subset of users / groups or organizations</p>"},{"location":"administration/audit/overview/#data-management","title":"Data management","text":"<p>Some history actions are already included in the \"basic knowledge\". (basic marker) </p> Read Create Delete Edit Platform knowledge basic basic basic Background tasks knowledge Knowledge files basic basic Global data import files Analyst workbenches files Triggers Workspaces Investigations User profile"},{"location":"administration/audit/overview/#user-actions","title":"User actions","text":"Supported Ask for file import Ask for data enrichment Ask for export generation Execute global search"},{"location":"administration/audit/triggers/","title":"Activity triggers","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/audit/triggers/#description","title":"Description","text":"<p>Having all the history in the user interface (events) is sometimes not enough to have a proactive monitoring. For this reason, you can configure some specific triggers to receive notifications on audit events. You can configure like personal triggers, lives one that will be sent directly or digest depending on your needs. </p>"},{"location":"administration/audit/triggers/#configuration","title":"Configuration","text":"<p>In this type of trigger, you will need to configure various options:</p> <ul> <li>Notification target: user interface or email,</li> <li>Recipients: the recipient of the notification,</li> <li>Filters: a set of filters to get only events that really interest you.</li> </ul>"},{"location":"administration/audit/triggers/#event-structure","title":"Event structure","text":"<p>In order to correctly configure the filters, here's a definition of the event structure</p> <ul> <li> <p>Event type: <code>authentication</code></p> <ul> <li>Event scopes: <code>login</code> and <code>logout</code> </li> </ul> </li> <li> <p>Event type: <code>read</code></p> <ul> <li>Event scopes: <code>read</code> and <code>unauthorized</code> </li> </ul> </li> <li> <p>Event type: <code>file</code></p> <ul> <li>Event scopes: <code>read</code>, <code>create</code> and <code>delete</code></li> </ul> </li> <li> <p>Event type: <code>mutation</code></p> <ul> <li>Event scopes: <code>unauthorized</code>, <code>update</code>, <code>create</code> and <code>delete</code></li> </ul> </li> <li> <p>Event type: <code>command</code></p> <ul> <li>Event scopes: <code>search</code>, <code>enrich</code>, <code>import</code> and <code>export</code></li> </ul> </li> </ul>"},{"location":"deployment/authentication/","title":"Authentication","text":""},{"location":"deployment/authentication/#introduction","title":"Introduction","text":"<p>OpenCTI supports several authentication providers. If you configure multiple strategies, they will be tested in the order you declared them.</p> <p>Activation</p> <p>You need to configure/activate only the authentication strategy that you really want to propose to your users.</p> <p>The product proposes two kinds of authentication strategies:</p> <ul> <li>Form (asking user for a user/password),</li> <li>Buttons (click with authentication on an external system).</li> </ul>"},{"location":"deployment/authentication/#supported-strategies","title":"Supported Strategies","text":"<p>Under the hood, we technically use the strategies provided by PassportJS. We integrate a subset of the strategies available with passport. If you need more, we can integrate other strategies.</p>"},{"location":"deployment/authentication/#local-users-form","title":"Local users (form)","text":"<p>This strategy uses the OpenCTI database as a user management.</p> <p>OpenCTI use this strategy as the default, but it's not the one we recommend for security reasons.</p> <pre><code>\"local\": {\n    \"strategy\": \"LocalStrategy\",\n    \"config\": {\n        \"disabled\": false\n    }\n}\n</code></pre> <p>Production deployment</p> <p>Please use the LDAP/Auth0/OpenID/SAML strategy for production deployment.</p>"},{"location":"deployment/authentication/#ldap-form","title":"LDAP (form)","text":"<p>This strategy can be used to authenticate your user with your company LDAP and is based on Passport - LDAPAuth.</p> <pre><code>\"ldap\": {\n    \"strategy\": \"LdapStrategy\",\n    \"config\": {\n        \"url\": \"ldaps://mydc.domain.com:686\",\n        \"bind_dn\": \"cn=Administrator,cn=Users,dc=mydomain,dc=com\",\n        \"bind_credentials\": \"MY_STRONG_PASSWORD\",\n        \"search_base\": \"cn=Users,dc=mydomain,dc=com\",\n        \"search_filter\": \"(cn={{username}})\",\n        \"mail_attribute\": \"mail\",\n        // \"account_attribute\": \"givenName\",\n        // \"firstname_attribute\": \"cn\",\n        // \"lastname_attribute\": \"cn\",\n        \"account_attrgroup_search_filteribute\": \"givenName\",\n        \"allow_self_signed\": true\n    }\n}\n</code></pre> <p>If you would like to use LDAP groups to automatically associate LDAP groups and OpenCTI groups/organizations:</p> <pre><code>\"ldap\": {\n    \"config\": {\n        ...\n        \"group_search_base\": \"cn=Groups,dc=mydomain,dc=com\",\n        \"group_search_filter\": \"(member={{dn}})\",\n        \"groups_management\": { // To map LDAP Groups to OpenCTI Groups\n            \"group_attribute\": \"cn\",\n            \"groups_mapping\": [\"LDAP_Group_1:OpenCTI_Group_1\", \"LDAP_Group_2:OpenCTI_Group_2\", ...]\n        },\n        \"organizations_management\": { // To map LDAP Groups to OpenCTI Organizations\n            \"organizations_path\": \"cn\",\n            \"organizations_mapping\": [\"LDAP_Group_1:OpenCTI_Organization_1\", \"LDAP_Group_2:OpenCTI_Organization_2\", ...]\n        }\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#saml-button","title":"SAML (button)","text":"<p>This strategy can be used to authenticate your user with your company SAML and is based on Passport - SAML.</p> <pre><code>\"saml\": {\n    \"identifier\": \"saml\",\n    \"strategy\": \"SamlStrategy\",\n    \"config\": {\n        \"issuer\": \"mytestsaml\",\n        // \"account_attribute\": \"nameID\",\n        // \"firstname_attribute\": \"nameID\",\n        // \"lastname_attribute\": \"nameID\",\n        \"entry_point\": \"https://auth.mydomain.com/auth/realms/mydomain/protocol/saml\",\n        \"saml_callback_url\": \"http://localhost:4000/auth/saml/callback\",\n        // \"private_key\": \"MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwg...\",\n        \"cert\": \"MIICmzCCAYMCBgF2Qt3X1zANBgkqhkiG9w0BAQsFADARMQ8w...\",\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>For the SAML strategy to work:</p> <ul> <li>The <code>cert</code> parameter is mandatory (PEM format) because it is used to validate the SAML response.</li> <li>The <code>private_key</code> (PEM format) is optional and is only required if you want to sign the SAML client request.</li> </ul> <p>Certificates</p> <p>Be careful to put the <code>cert</code> / <code>private_key</code>  key in PEM format. Indeed, a lot of systems generally export the keys in X509 / PCKS12 formats and so you will need to convert them.  Here is an example to extract PEM from PCKS12: <pre><code>openssl pkcs12 -in keystore.p12 -out newfile.pem -nodes\n</code></pre></p> <p>Here is an example of SAML configuration using environment variables:</p> <pre><code>- PROVIDERS__SAML__STRATEGY=SamlStrategy \n- \"PROVIDERS__SAML__CONFIG__LABEL=Login with SAML\"\n- PROVIDERS__SAML__CONFIG__ISSUER=mydomain\n- PROVIDERS__SAML__CONFIG__ENTRY_POINT=https://auth.mydomain.com/auth/realms/mydomain/protocol/saml\n- PROVIDERS__SAML__CONFIG__SAML_CALLBACK_URL=http://opencti.mydomain.com/auth/saml/callback\n- PROVIDERS__SAML__CONFIG__CERT=MIICmzCCAYMCBgF3Rt3X1zANBgkqhkiG9w0BAQsFADARMQ8w\n- PROVIDERS__SAML__CONFIG__LOGOUT_REMOTE=false\n</code></pre> <p>OpenCTI supports mapping SAML Roles/Groups on OpenCTI Groups. Here is an example:</p> <pre><code>\"saml\": {\n    \"config\": {\n        ...,\n        // Groups mapping\n        \"groups_management\": { // To map SAML Groups to OpenCTI Groups\n            \"group_attributes\": [\"Group\"],\n            \"groups_mapping\": [\"SAML_Group_1:OpenCTI_Group_1\", \"SAML_Group_2:OpenCTI_Group_2\", ...]\n        },\n        \"groups_management\": { // To map SAML Roles to OpenCTI Groups\n            \"group_attributes\": [\"Role\"],\n            \"groups_mapping\": [\"SAML_Role_1:OpenCTI_Group_1\", \"SAML_Role_2:OpenCTI_Group_2\", ...]\n        },\n        // Organizations mapping\n        \"organizations_management\": { // To map SAML Groups to OpenCTI Organizations\n            \"organizations_path\": [\"Group\"],\n            \"organizations_mapping\": [\"SAML_Group_1:OpenCTI_Organization_1\", \"SAML_Group_2:OpenCTI_Organization_2\", ...]\n        },\n        \"organizations_management\": { // To map SAML Roles to OpenCTI Organizations\n            \"organizations_path\": [\"Role\"],\n            \"organizations_mapping\": [\"SAML_Role_1:OpenCTI_Organization_1\", \"SAML_Role_2:OpenCTI_Organization_2\", ...]\n        }\n    }\n}\n</code></pre> <p>Here is an example of SAML Groups mapping configuration using environment variables:</p> <pre><code>- \"PROVIDERS__SAML__CONFIG__GROUPS_MANAGEMENT__GROUP_ATTRIBUTES=[\\\"Group\\\"]\"\n- \"PROVIDERS__SAML__CONFIG__GROUPS_MANAGEMENT__GROUPS_MAPPING=[\\\"SAML_Group_1:OpenCTI_Group_1\\\", \\\"SAML_Group_2:OpenCTI_Group_2\\\", ...]\"\n</code></pre>"},{"location":"deployment/authentication/#auth0-button","title":"Auth0 (button)","text":"<p>This strategy allows to use Auth0 Service to handle the authentication and is based on Passport - Auth0.</p> <pre><code>\"authzero\": {\n    \"identifier\": \"auth0\",\n    \"strategy\": \"Auth0Strategy\",\n    \"config\": {\n        \"clientID\": \"XXXXXXXXXXXXXXXXXX\",\n        \"baseURL\": \"https://opencti.mydomain.com\",\n        \"clientSecret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/auth0/callback\",\n        \"domain\": \"mycompany.eu.auth0.com\",\n        \"audience\": \"XXXXXXXXXXXXXXX\",\n        \"scope\": \"openid email profile XXXXXXXXXXXXXXX\",\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>Here is an example of Auth0 configuration using environment variables:</p> <pre><code>- PROVIDERS__AUTHZERO__STRATEGY=Auth0Strategy\n- PROVIDERS__AUTHZERO__CONFIG__CLIENT_ID=${AUTH0_CLIENT_ID}\n- PROVIDERS__AUTHZERO__CONFIG__BASEURL=${AUTH0_BASE_URL}\n- PROVIDERS__AUTHZERO__CONFIG__CLIENT_SECRET=${AUTH0_CLIENT_SECRET}\n- PROVIDERS__AUTHZERO__CONFIG__CALLBACK_URL=${AUTH0_CALLBACK_URL}\n- PROVIDERS__AUTHZERO__CONFIG__DOMAIN=${AUTH0_DOMAIN}\n- \"PROVIDERS__AUTHZERO__CONFIG__SCOPE=openid email profile\"\n- PROVIDERS__AUTHZERO__CONFIG__LOGOUT_REMOTE=false\n</code></pre>"},{"location":"deployment/authentication/#openid-connect-button","title":"OpenID Connect (button)","text":"<p>This strategy allows to use the OpenID Connect Protocol to handle the authentication and is based on Node OpenID Client which is more powerful than the passport one.</p> <pre><code>\"oic\": {\n    \"identifier\": \"oic\",\n    \"strategy\": \"OpenIDConnectStrategy\",\n    \"config\": {\n        \"label\": \"Login with OpenID\",\n        \"issuer\": \"https://auth.mydomain.com/auth/realms/mydomain\",\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"redirect_uris\": [\"https://opencti.mydomain.com/auth/oic/callback\"],\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>Here is an example of OpenID configuration using environment variables:</p> <pre><code>- PROVIDERS__OPENID__STRATEGY=OpenIDConnectStrategy \n- \"PROVIDERS__OPENID__CONFIG__LABEL=Login with OpenID\"\n- PROVIDERS__OPENID__CONFIG__ISSUER=https://auth.mydomain.com/auth/realms/xxxx\n- PROVIDERS__OPENID__CONFIG__CLIENT_ID=XXXXXXXXXXXXXXXXXX\n- PROVIDERS__OPENID__CONFIG__CLIENT_SECRET=XXXXXXXXXXXXXXXXXX\n- \"PROVIDERS__OPENID__CONFIG__REDIRECT_URIS=[\\\"https://opencti.mydomain.com/auth/oic/callback\\\"]\"\n- PROVIDERS__OPENID__CONFIG__LOGOUT_REMOTE=false\n</code></pre> <p>OpenCTI support mapping OpenID Claims on OpenCTI Groups (everything is tied to a group in the platform). Here is an example:</p> <pre><code>\"oic\": {\n    \"config\": {\n        ...,\n        // Groups mapping\n        \"groups_management\": { // To map OpenID Claims to OpenCTI Groups\n            \"groups_scope\": \"groups\",\n            \"groups_path\": [\"groups\", \"realm_access.groups\", \"resource_access.account.groups\"],\n            \"groups_mapping\": [\"OpenID_Group_1:OpenCTI_Group_1\", \"OpenID_Group_2:OpenCTI_Group_2\", ...]\n        },\n        // Organizations mapping  \n        \"organizations_management\": { // To map OpenID Claims to OpenCTI Organizations\n            \"organizations_scope\": \"groups\",\n            \"organizations_path\": [\"groups\", \"realm_access.groups\", \"resource_access.account.groups\"],\n            \"organizations_mapping\": [\"OpenID_Group_1:OpenCTI_Group_1\", \"OpenID_Group_2:OpenCTI_Group_2\", ...]\n        },\n    }\n}\n</code></pre> <p>Here is an example of OpenID Groups mapping configuration using environment variables:</p> <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_SCOPE=groups\n- \"PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_PATH=[\\\"groups\\\", \\\"realm_access.groups\\\", \\\"resource_access.account.groups\\\"]\"\n- \"PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_MAPPING=[\\\"OpenID_Group_1:OpenCTI_Group_1\\\", \\\"OpenID_Group_2:OpenCTI_Group_2\\\", ...]\"\n</code></pre> <p>By default, the claims are mapped based on the content of the JWT <code>access_token</code>. If you want to map claims which are in other JWT (such as <code>id_token</code>), you can define the following environment variables:</p> <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__TOKEN_REFERENCE=id_token\n- PROVIDERS__OPENID__CONFIG__ORGANISATIONS_MANAGEMENT__TOKEN_REFERENCE=id_token\n</code></pre> <p>Alternatively, you can request OpenCTI to use claims from the <code>userinfo</code> endpoint instead of a JWT. <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__READ_USERINFO=true\n- PROVIDERS__OPENID__CONFIG__ORGANISATIONS_MANAGEMENT__READ_USERINFO=true\n</code></pre></p>"},{"location":"deployment/authentication/#facebook-button","title":"Facebook (button)","text":"<p>This strategy can authenticate your users with Facebook and is based on Passport - Facebook.</p> <pre><code>\"facebook\": {\n    \"identifier\": \"facebook\",\n    \"strategy\": \"FacebookStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/facebook/callback\",\n        \"logout_remote\": false\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#google-button","title":"Google (button)","text":"<p>This strategy can authenticate your users with Google and is based on Passport - Google.</p> <pre><code>\"google\": {\n    \"identifier\": \"google\",\n    \"strategy\": \"GoogleStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/google/callback\",\n        \"logout_remote\": false\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#github-button","title":"GitHub (button)","text":"<p>This strategy can authenticate your users with GitHub and is based on Passport - GitHub.</p> <pre><code>\"github\": {\n    \"identifier\": \"github\",\n    \"strategy\": \"GithubStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/github/callback\",\n        \"logout_remote\": false\n  }\n}\n</code></pre>"},{"location":"deployment/authentication/#client-certificate-button","title":"Client certificate (button)","text":"<p>This strategy can authenticate a user based on SSL client certificates. For this, you need to configure OpenCTI to start in HTTPS, for example:</p> <pre><code>\"port\": 443,\n\"https_cert\": {\n    \"key\": \"/cert/server_key.pem\",\n    \"crt\": \"/cert/server_cert.pem\",\n    \"reject_unauthorized\": true\n}\n</code></pre> <p>And then add the <code>ClientCertStrategy</code>:</p> <pre><code>\"cert\": {\n    \"strategy\":\"ClientCertStrategy\",\n    \"config\": {\n        \"label\":\"CLIENT CERT\"\n    }\n}\n</code></pre> <p>Afterwards, when accessing for the first time OpenCTI, the browser will ask for the certificate you want to use.</p>"},{"location":"deployment/authentication/#proxy-headers-automatic","title":"Proxy headers (automatic)","text":"<p>This strategy can authenticate the users directly from trusted headers.</p> <pre><code>{\n  \"header\": {\n    \"strategy\": \"HeaderStrategy\",\n    \"config\": {\n      \"disabled\": false,\n      \"header_email\": \"auth_email_address\",\n      \"header_name\": \"auth_name\",\n      \"header_firstname\": \"auth_firstname\",\n      \"header_lastname\": \"auth_lastname\",\n      \"logout_uri\": \"https://www.filigran.io\",\n      \"groups_management\": {\n        \"groups_header\": \"auth_groups\",\n        \"groups_splitter\": \",\",\n        \"groups_mapping\": [\"admin:admin\", \"root:root\"]\n      },\n      \"organizations_management\": {\n        \"organizations_header\": \"auth_institution\",\n        \"organizations_splitter\": \",\",\n        \"organizations_mapping\": [\"test:test\"]\n      }\n    }\n  }\n}\n</code></pre> <p>If this mode is activated and the headers are available, the user will be automatically logged without any action or notice. The logout uri will remove the session and redirect to the configured uri. If not specified, the redirect will be done to the request referer and so the header authentication will be done again.</p>"},{"location":"deployment/authentication/#automatically-create-group-on-sso","title":"Automatically create group on SSO","text":"<p>The variable auto_create_group can be added in the options of some strategies (LDAP, SAML and OpenID). If this variable is true, the groups of a user that logins will automatically be created if they don\u2019t exist.</p> <p>More precisely, if the user that tries to authenticate has groups that don\u2019t exist in OpenCTI but exist in the SSO configuration, there are two cases:</p> <ul> <li>if auto_create_group= true in the SSO configuration: the groups are created at the platform initialization and the user will be mapped on them.</li> <li>else: an error is raised.</li> </ul> <p>Example</p> <p>We assume that Group1 exists in the platform, and newGroup doesn\u2019t exist. The user that tries to log in has the group newGroup. If auto_create_group = true in the SSO configuration, the group named newGroup will be created at the platform initialization and the user will be mapped on it. If auto_create_group = false or is undefined, the user can\u2019t log in and an error is raised.</p> <pre><code>\"groups_management\": {\n  \"group_attribute\": \"cn\",\n  \"groups_mapping\": [\"SSO_GROUP_NAME1:group1\", \"SSO_GROUP_NAME_2:newGroup\", ...]\n},\n\"auto_create_group\": true\n</code></pre>"},{"location":"deployment/authentication/#examples","title":"Examples","text":""},{"location":"deployment/authentication/#ldap-then-fallback-to-local","title":"LDAP then fallback to local","text":"<p>In this example the users have a login form and need to enter login and password. The authentication is done on LDAP first, then locally if user failed to authenticate and finally fail if none of them succeeded. Here is an example for the <code>production.json</code> file:</p> <pre><code>\"providers\": {\n    \"ldap\": {\n        \"strategy\": \"LdapStrategy\",\n        \"config\": {\n            \"url\": \"ldaps://mydc.mydomain.com:636\",\n            \"bind_dn\": \"cn=Administrator,cn=Users,dc=mydomain,dc=com\",\n            \"bind_credentials\": \"MY_STRONG_PASSWORD\",\n            \"search_base\": \"cn=Users,dc=mydomain,dc=com\",\n            \"search_filter\": \"(cn={{username}})\",\n            \"mail_attribute\": \"mail\",\n            \"account_attribute\": \"givenName\"\n        }\n    },\n    \"local\": {\n        \"strategy\": \"LocalStrategy\",\n        \"config\": {\n            \"disabled\": false\n        }\n    }\n}\n</code></pre> <p>If you use a container deployment, here is an example using environment variables:</p> <pre><code>- PROVIDERS__LDAP__STRATEGY=LdapStrategy\n- PROVIDERS__LDAP__CONFIG__URL=ldaps://mydc.mydomain.org:636\n- PROVIDERS__LDAP__CONFIG__BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=com\n- PROVIDERS__LDAP__CONFIG__BIND_CREDENTIALS=XXXXXXXXXX\n- PROVIDERS__LDAP__CONFIG__SEARCH_BASE=cn=Users,dc=mydomain,dc=com\n- PROVIDERS__LDAP__CONFIG__SEARCH_FILTER=(cn={{username}})\n- PROVIDERS__LDAP__CONFIG__MAIL_ATTRIBUTE=mail\n- PROVIDERS__LDAP__CONFIG__ACCOUNT_ATTRIBUTE=givenName\n- PROVIDERS__LDAP__CONFIG__ALLOW_SELF_SIGNED=true\n- PROVIDERS__LOCAL__STRATEGY=LocalStrategy\n</code></pre>"},{"location":"deployment/clustering/","title":"Clustering","text":""},{"location":"deployment/clustering/#introduction","title":"Introduction","text":"<p>The OpenCTI platform technological stack has been designed to be able to scale horizontally. All dependencies such as Elastic or Redis can be deployed in cluster mode and performances can be drastically increased by deploying multiple platform and worker instances.</p>"},{"location":"deployment/clustering/#high-level-architecture","title":"High level architecture","text":"<p>Here is the high level architecture for customers and Filigran cloud platform to ensure both high availability and throughput.</p> <p></p>"},{"location":"deployment/clustering/#configuration","title":"Configuration","text":""},{"location":"deployment/clustering/#dependencies","title":"Dependencies","text":""},{"location":"deployment/clustering/#elasticsearch","title":"ElasticSearch","text":"<p>In the ElasticSearch configuration of OpenCTI, it is possible to declare all nodes.</p> <pre><code>- \"ELASTICSEARCH__URL=[\\\"https://user:pass@node1:9200\\\", \\\"https://user:pass@node2:9200\\\", ...]\"\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with OpenSearch and AWS / GCP / Azure native search services based on the ElasticSearch query language.</p>"},{"location":"deployment/clustering/#redis","title":"Redis","text":"<p>Redis should be turned to cluster mode:</p> <pre><code>- REDIS__MODE=cluster\n- \"REDIS__HOSTNAMES=[\\\"node1:6379\\\", \\\"node2:6379\\\", ...]\"\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with ElastiCache, MemoryStore and AWS / GCP / Azure native services based on the Redis protocol.</p>"},{"location":"deployment/clustering/#rabbitmq","title":"RabbitMQ","text":"<p>For the RabbitMQ cluster, you will need a TCP load balancer on top of the nodes since the configuration does not support multi-nodes for now:</p> <pre><code>- RABBITMQ__HOSTNAME=load-balancer-rabbitmq\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with Amazon MQ, CloudAMQP and AWS / GCP / Azure native services based on the AMQP protocol.</p>"},{"location":"deployment/clustering/#s3-bucket-minio","title":"S3 bucket / MinIO","text":"<p>MinIO is an open source server able to serve S3 buckets. It can be deployed in cluster mode and is compatible with several storage backend. OpenCTI is compatible with any tool following the S3 standard.</p>"},{"location":"deployment/clustering/#platform","title":"Platform","text":"<p>As showed on the schema, best practices for cluster mode and to avoid any congestion in the technological stack are:</p> <ul> <li>Deploy platform(s) dedicated to end users and connectors registration</li> <li>Deploy platform(s) dedicated to workers / ingestion process<ul> <li>We recommend 3 to 4 workers maximum by OpenCTI instance.</li> <li>The ingestion platforms will never be accessed directly by end users.</li> </ul> </li> </ul> <p>When enabling clustering, the number of nodes is displayed in Settings &gt; Parameters.</p> <p></p>"},{"location":"deployment/clustering/#managers-and-schedulers","title":"Managers and schedulers","text":"<p>Also, since some managers like the rule engine, the task manager and the notification manager can take some resources in the OpenCTI NodeJS process, it is highly recommended to disable them in the frontend cluster. OpenCTI automatically handle the distribution and the launching of the engines across all nodes in the cluster except where they are explicitly disabled in the configuration.</p> <p></p>"},{"location":"deployment/configuration/","title":"Configuration","text":"<p>The purpose of this section is to learn how to configure OpenCTI to have it tailored for your production and development needs. It is possible to check all default parameters implemented in the platform in the <code>default.json</code> file.</p> <p>Here are the configuration keys, for both containers (environment variables) and manual deployment.</p> <p>Parameters equivalence</p> <p>The equivalent of a config variable in environment variables is the usage of a double underscores (<code>__</code>) for a level of config.</p> <p>For example: <pre><code>\"providers\": {\n  \"ldap\": {\n    \"strategy\": \"LdapStrategy\"\n  }\n}\n</code></pre></p> <p>will become: <pre><code>PROVIDERS__LDAP__STRATEGY=LdapStrategy\n</code></pre></p> <p>If you need to put a list of elements for the key, it must have a special formatting. Here is an example for redirect URIs for OpenID config: <pre><code>\"PROVIDERS__OPENID__CONFIG__REDIRECT_URIS=[\\\"https://demo.opencti.io/auth/oic/callback\\\"]\"\n</code></pre></p>"},{"location":"deployment/configuration/#platform","title":"Platform","text":""},{"location":"deployment/configuration/#api-frontend","title":"API &amp; Frontend","text":""},{"location":"deployment/configuration/#basic-parameters","title":"Basic parameters","text":"Parameter Environment variable Default value Description app:port APP__PORT 4000 Listen port of the application app:base_path APP__BASE_PATH Specific URI (ie. /opencti) app:base_url APP__BASE_URL http://localhost:4000 Full URL of the platform (should include the <code>base_path</code> if any) app:request_timeout APP__REQUEST_TIMEOUT 1200000 Request timeout, in ms (default 20 minutes) app:session_timeout APP__SESSION_TIMEOUT 1200000 Session timeout, in ms (default 20 minutes) app:session_idle_timeout APP__SESSION_IDLE_TIMEOUT 0 Idle timeout (locking the screen), in ms (default 0 minute - disabled) app:session_cookie APP__SESSION_COOKIE false Use memory/session cookie instead of persistent one app:admin:email APP__ADMIN__EMAIL admin@opencti.io Default login email of the admin user app:admin:password APP__ADMIN__PASSWORD ChangeMe Default password of the admin user app:admin:token APP__ADMIN__TOKEN ChangeMe Default token (must be a valid UUIDv4) app:health_access_key APP__HEALTH_ACCESS_KEY ChangeMe Access key for the <code>/health</code> endpoint. Must be changed - will not respond to default value. Access with <code>/health?health_access_key=ChangeMe</code>"},{"location":"deployment/configuration/#network-and-security","title":"Network and security","text":"Parameter Environment variable Default value Description http_proxy HTTP_PROXY Proxy URL for HTTP connection (example: http://proxy:80080) https_proxy HTTPS_PROXY Proxy URL for HTTPS connection (example: http://proxy:80080) no_proxy NO_PROXY Comma separated list of hostnames for proxy exception (example: localhost,127.0.0.0/8,internal.opencti.io) app:https_cert:cookie_secure APP__HTTPS_CERT__COOKIE_SECURE false Set the flag \"secure\" for session cookies. app:https_cert:ca APP__HTTPS_CERT__CA Empty list [] Certificate authority paths or content, only if the client uses a self-signed certificate. app:https_cert:key APP__HTTPS_CERT__KEY Certificate key path or content app:https_cert:crt APP__HTTPS_CERT__CRT Certificate crt path or content app:https_cert:reject_unauthorized APP__HTTPS_CERT__REJECT_UNAUTHORIZED If not false, the server certificate is verified against the list of supplied CAs"},{"location":"deployment/configuration/#logging","title":"Logging","text":""},{"location":"deployment/configuration/#errors","title":"Errors","text":"Parameter Environment variable Default value Description app:app_logs:logs_level APP__APP_LOGS__LOGS_LEVEL info The application log level app:app_logs:logs_files APP__APP_LOGS__LOGS_FILES <code>true</code> If application logs is logged into files app:app_logs:logs_console APP__APP_LOGS__LOGS_CONSOLE <code>true</code> If application logs is logged to console (useful for containers) app:app_logs:logs_max_files APP__APP_LOGS__LOGS_MAX_FILES 7 Maximum number of daily files in logs app:app_logs:logs_directory APP__APP_LOGS__LOGS_DIRECTORY ./logs File logs directory"},{"location":"deployment/configuration/#audit","title":"Audit","text":"Parameter Environment variable Default value Description app:audit_logs:logs_files APP__AUDIT_LOGS__LOGS_FILES <code>true</code> If audit logs is logged into files app:audit_logs:logs_console APP__AUDIT_LOGS__LOGS_CONSOLE <code>true</code> If audit logs is logged to console (useful for containers) app:audit_logs:logs_max_files APP__AUDIT_LOGS__LOGS_MAX_FILES 7 Maximum number of daily files in logs app:audit_logs:logs_directory APP__AUDIT_LOGS__LOGS_DIRECTORY ./logs Audit logs directory"},{"location":"deployment/configuration/#telemetry","title":"Telemetry","text":"Parameter Environment variable Default value Description app:telemetry:metrics:enabled APP__TELEMETRY__METRICS__ENABLED <code>false</code> Enable the metrics collection. app:telemetry:metrics:exporter_otlp APP__TELEMETRY__METRICS__EXPORTER_OTLP Port to expose the OTLP endpoint. app:telemetry:metrics:exporter_prometheus APP__TELEMETRY__METRICS__EXPORTER_PROMETHEUS 14269 Port to expose the Prometheus endpoint."},{"location":"deployment/configuration/#maps-references","title":"Maps &amp; references","text":"Parameter Environment variable Default value Description app:map_tile_server_dark APP__MAP_TILE_SERVER_DARK https://map.opencti.io/styles/filigran-dark2/{z}/{x}/{y}.png The address of the OpenStreetMap provider with dark theme style app:map_tile_server_light APP__MAP_TILE_SERVER_LIGHT https://map.opencti.io/styles/filigran-light2/{z}/{x}/{y}.png The address of the OpenStreetMap provider with light theme style app:reference_attachment APP__REFERENCE_ATTACHMENT <code>false</code> External reference mandatory attachment"},{"location":"deployment/configuration/#functional-customization","title":"Functional customization","text":"Parameter Environment variable Default value Description app:artifact_zip_password APP__ARTIFACT_ZIP_PASSWORD infected Artifact encrypted archive default password relations_deduplication:past_days RELATIONS_DEDUPLICATION__PAST_DAYS 30 De-duplicate relations based on <code>start_time</code> and <code>stop_time</code> - n days relations_deduplication:next_days RELATIONS_DEDUPLICATION__NEXT_DAYS 30 De-duplicate relations based on <code>start_time</code> and <code>stop_time</code> + n days relations_deduplication:created_by_based RELATIONS_DEDUPLICATION__CREATED_BY_BASED <code>false</code> Take into account the author to duplicate even if <code>stat_time</code> / <code>stop_time</code> are matching relations_deduplication:types_overrides:relationship_type:past_days RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__PAST_DAYS Override the past days for a specific type of relationship (ex. targets) relations_deduplication:types_overrides:relationship_type:next_days RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__NEXT_DAYS Override the next days for a specific type of relationship (ex. targets) relations_deduplication:types_overrides:relationship_type:created_by_based RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__CREATED_BY_BASED Override the author duplication for a specific type of relationship (ex. targets)"},{"location":"deployment/configuration/#technical-customization","title":"Technical customization","text":"Parameter Environment variable Default value Description app:graphql:playground:enabled APP__GRAPHQL__PLAYGROUND__ENABLED <code>true</code> Enable the playground on /graphql app:graphql:playground:force_disabled_introspection APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION <code>true</code> Introspection is allowed to auth users but can be disabled in needed app:concurrency:retry_count APP__CONCURRENCY__RETRY_COUNT 200 Number of try to get the lock to work an element (create/update/merge, ...) app:concurrency:retry_delay APP__CONCURRENCY__RETRY_DELAY 100 Delay between 2 lock retry (in milliseconds) app:concurrency:retry_jitter APP__CONCURRENCY__RETRY_JITTER 50 Random jitter to prevent concurrent retry  (in milliseconds) app:concurrency:max_ttl APP__CONCURRENCY__MAX_TTL 30000 Global maximum time for lock retry (in milliseconds)"},{"location":"deployment/configuration/#dependencies","title":"Dependencies","text":""},{"location":"deployment/configuration/#xtm-suite","title":"XTM Suite","text":"Parameter Environment variable Default value Description xtm:openbas_url XTM__OPENBAS_URL OpenBAS URL xtm:openbas_token XTM__OPENBAS_TOKEN OpenBAS token xtm:openbas_reject_unauthorized XTM__OPENBAS_REJECT_UNAUTHORIZED false Enable TLS certificate check xtm:openbas_disable_display XTM__OPENBAS_DISABLE_DISPLAY false Disable OpenBAS posture in the UI"},{"location":"deployment/configuration/#elasticsearch","title":"ElasticSearch","text":"Parameter Environment variable Default value Description elasticsearch:engine_selector ELASTICSEARCH__ENGINE_SELECTOR auto <code>elk</code> or <code>opensearch</code>, default is <code>auto</code>, please put <code>elk</code> if you use token auth. elasticsearch:engine_check ELASTICSEARCH__ENGINE_CHECK false Disable Search Engine compatibility matrix verification.  Caution: OpenCTI was developed in compliance with the compatibility matrix. Setting the parameter to <code>true</code> may result in negative impacts. elasticsearch:url ELASTICSEARCH__URL http://localhost:9200 URL(s) of the ElasticSearch (supports http://user:pass@localhost:9200 and list of URLs) elasticsearch:username ELASTICSEARCH__USERNAME Username can be put in the URL or with this parameter elasticsearch:password ELASTICSEARCH__PASSWORD Password can be put in the URL or with this parameter elasticsearch:api_key ELASTICSEARCH__API_KEY API key for ElasticSearch token auth. Please set also <code>engine_selector</code> to <code>elk</code> elasticsearch:index_prefix ELASTICSEARCH__INDEX_PREFIX opencti Prefix for the indices elasticsearch:ssl:reject_unauthorized ELASTICSEARCH__SSL__REJECT_UNAUTHORIZED <code>true</code> Enable TLS certificate check elasticsearch:ssl:ca ELASTICSEARCH__SSL__CA Custom certificate path or content elasticsearch:search_wildcard_prefix ELASTICSEARCH__SEARCH_WILDCARD_PREFIX <code>false</code> Search includes words with automatic fuzzy comparison elasticsearch:search_fuzzy ELASTICSEARCH__SEARCH_FUZZY <code>false</code> Search will include words not starting with the search keyword"},{"location":"deployment/configuration/#redis","title":"Redis","text":"Parameter Environment variable Default value Description redis:mode REDIS__MODE single Connect to redis in \"single\", \"sentinel or \"cluster\"  mode redis:namespace REDIS__NAMESPACE Namespace (to use as prefix) redis:hostname REDIS__HOSTNAME localhost Hostname of the Redis Server redis:hostnames REDIS__HOSTNAMES Hostnames definition for Redis cluster or sentinel mode: a list of host:port objects. redis:port REDIS__PORT 6379 Port of the Redis Server redis:sentinel_master_name REDIS__SENTINEL_MASTER_NAME Name of your Redis Sentinel Master (mandatory in sentinel mode) redis:use_ssl REDIS__USE_SSL <code>false</code> Is the Redis Server has TLS enabled redis:username REDIS__USERNAME Username of the Redis Server redis:password REDIS__PASSWORD Password of the Redis Server redis:ca REDIS__CA [] List of path(s) of the CA certificate(s) redis:trimming REDIS__TRIMMING 2000000 Number of elements to maintain in the stream. (0 = unlimited)"},{"location":"deployment/configuration/#rabbitmq","title":"RabbitMQ","text":"Parameter Environment variable Default value Description rabbitmq:hostname RABBITMQ__HOSTNAME localhost 7 Hostname of the RabbitMQ server rabbitmq:port RABBITMQ__PORT 5672 Port of the RabbitMQ server rabbitmq:port_management RABBITMQ__PORT_MANAGEMENT 15672 Port of the RabbitMQ Management Plugin rabbitmq:username RABBITMQ__USERNAME guest RabbitMQ user rabbitmq:password RABBITMQ__PASSWORD guest RabbitMQ password rabbitmq:queue_type RABBITMQ__QUEUE_TYPE \"classic\" RabbitMQ Queue Type (\"classic\" or \"quorum\") - - - - rabbitmq:use_ssl RABBITMQ__USE_SSL <code>false</code> Use TLS connection rabbitmq:use_ssl_cert RABBITMQ__USE_SSL_CERT Path or cert content rabbitmq:use_ssl_key RABBITMQ__USE_SSL_KEY Path or key content rabbitmq:use_ssl_pfx RABBITMQ__USE_SSL_PFX Path or pfx content rabbitmq:use_ssl_ca RABBITMQ__USE_SSL_CA [] List of path(s) of the CA certificate(s) rabbitmq:use_ssl_passphrase RABBITMQ__SSL_PASSPHRASE Passphrase for the key certificate rabbitmq:use_ssl_reject_unauthorized RABBITMQ__SSL_REJECT_UNAUTHORIZED <code>false</code> Reject rabbit self signed certificate - - - - rabbitmq:management_ssl RABBITMQ__MANAGEMENT_SSL <code>false</code> Is the Management Plugin has TLS enabled rabbitmq:management_ssl_reject_unauthorized RABBITMQ__SSL_REJECT_UNAUTHORIZED <code>true</code> Reject management self signed certificate"},{"location":"deployment/configuration/#s3-bucket","title":"S3 Bucket","text":"Parameter Environment variable Default value Description minio:endpoint MINIO__ENDPOINT localhost Hostname of the S3 Service. Example if you use AWS Bucket S3: s3.us-east-1.amazonaws.com (if <code>minio:bucket_region</code> value is us-east-1). This parameter value can be omitted if you use Minio as an S3 Bucket Service. minio:port MINIO__PORT 9000 Port of the S3 Service. For AWS Bucket S3 over HTTPS, this value can be changed (usually 443). minio:use_ssl MINIO__USE_SSL <code>false</code> Indicates whether the S3 Service has TLS enabled. For AWS Bucket S3 over HTTPS, this value could be <code>true</code>. minio:access_key MINIO__ACCESS_KEY ChangeMe Access key for the S3 Service. minio:secret_key MINIO__SECRET_KEY ChangeMe Secret key for the S3 Service. minio:bucket_name MINIO__BUCKET_NAME opencti-bucket S3 bucket name. Useful to change if you use AWS. minio:bucket_region MINIO__BUCKET_REGION us-east-1 Region of the S3 bucket if you are using AWS. This parameter value can be omitted if you use Minio as an S3 Bucket Service. minio:use_aws_role MINIO__USE_AWS_ROLE <code>false</code> Indicates whether to use AWS role auto credentials. When this parameter is configured, the <code>minio:access_key</code> and <code>minio:secret_key</code> parameters are not necessary."},{"location":"deployment/configuration/#smtp-service","title":"SMTP Service","text":"Parameter Environment variable Default value Description smtp:hostname SMTP__HOSTNAME SMTP Server hostname smtp:port SMTP__PORT 465 SMTP Port (25 or 465 for TLS) smtp:use_ssl SMTP__USE_SSL <code>false</code> SMTP over TLS smtp:reject_unauthorized SMTP__REJECT_UNAUTHORIZED <code>false</code> Enable TLS certificate check smtp:username SMTP__USERNAME SMTP Username if authentication is needed smtp:password SMTP__PASSWORD SMTP Password if authentication is needed"},{"location":"deployment/configuration/#ai-service","title":"AI Service","text":"<p>AI deployment and cloud services</p> <p>There are several possibilities for Enterprise Edition customers to use OpenCTI AI endpoints:</p> <ul> <li>Use the Filigran AI Service leveraging our custom AI model using the token given by the support team.</li> <li>Use OpenAI or MistralAI cloud endpoints using your own tokens.</li> <li>Deploy or use local AI endpoints (Filigran can provide you with the custom model).</li> </ul> Parameter Environment variable Default value Description ai:enabled AI__ENABLED true Enable AI capabilities ai:type AI__TYPE mistralai AI type (<code>mistralai</code> or <code>openai</code>) ai:endpoint AI__ENDPOINT Endpoint URL (empty means default cloud service) ai:token AI__TOKEN Token for endpoint credentials ai:model AI__MODEL Model to be used for text generation (depending on type) ai:model_images AI__MODEL_IMAGES Model to be used for image generation (depending on type)"},{"location":"deployment/configuration/#using-a-credentials-provider","title":"Using a credentials provider","text":"<p>In some cases, it may not be possible to put directly dependencies credentials directly in environment variables or static configuration. The platform can then retrieve them from a credentials provider. Here is the list of supported providers:</p> Credentials provider Provider key CyberArk <code>cyberark</code> <p>For each dependency, special configuration keys are available to ensure the platform retrieves credentials during start process. Not all dependencies support this mechanism, here is the exhaustive list:</p> Dependency Prefix ElasticSearch <code>elasticsearch</code> S3 Storage <code>minio</code> Redis <code>redis</code> OpenID secrets <code>oic</code>"},{"location":"deployment/configuration/#common-configurations","title":"Common configurations","text":"Parameter Environment variable Default value Description <code>{prefix}</code>:credentials_provider:https_cert:reject_unauthorized <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__REJECT_UNAUTHORIZED <code>false</code> Reject unauthorized TLS connection <code>{prefix}</code>:credentials_provider:https_cert:crt <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__CRT Path to the HTTPS certificate <code>{prefix}</code>:credentials_provider:https_cert:key <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__KEY Path to the HTTPS key <code>{prefix}</code>:credentials_provider:https_cert:ca <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__CA Path to the HTTPS CA certificate"},{"location":"deployment/configuration/#cyberark","title":"CyberArk","text":"Parameter Environment variable Default value Description <code>{prefix}</code>:credentials_provider:cyberark:uri <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__URI The URL of the CyberArk endpoint for credentials retrieval (GET request) <code>{prefix}</code>:credentials_provider:cyberark:app_id <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__APP_ID The used application ID for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:safe <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__SAFE The used safe key for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:object <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__OBJECT The used object key for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:default_splitter <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER : Default splitter of the credentials results, for \"username:password\", default is \":\" <code>{prefix}</code>:credentials_provider:cyberark:field_targets <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS [] Fields targets in the data content response after splitting <p>Here is an example for ElasticSearch:</p> <p>Environment variables: <pre><code>- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__URI=http://my.cyberark.com/AIMWebService/api/Accounts\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__APP_ID=opencti-elastic\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__SAFE=mysafe-key\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__OBJECT=myobject-key\n- \"ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER=:\" # As default is already \":\", may not be necessary\n- \"ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS=[\\\"username\\\",\\\"password\\\"]\"\n</code></pre></p> <p>JSON version: <pre><code>\"elasticsearch\": {\n    \"credentials_provider\": {\n        \"cyberark\": {\n            \"uri\": \"http://my.cyberark.com/AIMWebService/api/Accounts\",\n            \"app_id\": \"opencti-elastic\",\n            \"safe\": \"mysafe-key\",\n            \"object\": \"myobject-key\",\n            \"default_splitter\": \":\",\n            \"field_targets\": [\"username\", \"password\"]\n      }\n    }\n}\n</code></pre></p> <p>Another example for MinIo (S3) using certificate:</p> <p>Environment variables: <pre><code>- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__CRT=/cert_volume/mycert.crt\n- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__KEY=/cert_volume/mycert.key\n- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__CA=/cert_volume/ca.crt\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__URI=http://my.cyberark.com/AIMWebService/api/Accounts\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__APP_ID=opencti-s3\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__SAFE=mysafe-key\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__OBJECT=myobject-key\n- \"MINIO__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER=:\" # As default is already \":\", may not be necessary\n- \"MINIO__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS=[\\\"access_key\\\",\\\"secret_key\\\"]\"\n</code></pre></p>"},{"location":"deployment/configuration/#engines-schedules-and-managers","title":"Engines, Schedules and Managers","text":"Parameter Environment variable Default value Description rule_engine:enabled RULE_ENGINE__ENABLED <code>true</code> Enable/disable the rule engine rule_engine:lock_key RULE_ENGINE__LOCK_KEY rule_engine_lock Lock key of the engine in Redis - - - - history_manager:enabled HISTORY_MANAGER__ENABLED <code>true</code> Enable/disable the history manager history_manager:lock_key HISTORY_MANAGER__LOCK_KEY history_manager_lock Lock key for the manager in Redis - - - - task_scheduler:enabled TASK_SCHEDULER__ENABLED <code>true</code> Enable/disable the task scheduler task_scheduler:lock_key TASK_SCHEDULER__LOCK_KEY task_manager_lock Lock key for the scheduler in Redis task_scheduler:interval TASK_SCHEDULER__INTERVAL 10000 Interval to check new task to do (in ms) - - - - sync_manager:enabled SYNC_MANAGER__ENABLED <code>true</code> Enable/disable the sync manager sync_manager:lock_key SYNC_MANAGER__LOCK_KEY sync_manager_lock Lock key for the manager in Redis sync_manager:interval SYNC_MANAGER__INTERVAL 10000 Interval to check new sync feeds to consume (in ms) - - - - expiration_scheduler:enabled EXPIRATION_SCHEDULER__ENABLED <code>true</code> Enable/disable the scheduler expiration_scheduler:lock_key EXPIRATION_SCHEDULER__LOCK_KEY expired_manager_lock Lock key for the scheduler in Redis expiration_scheduler:interval EXPIRATION_SCHEDULER__INTERVAL 300000 Interval to check expired indicators (in ms) - - - - retention_manager:enabled RETENTION_MANAGER__ENABLED <code>true</code> Enable/disable the retention manager retention_manager:lock_key RETENTION_MANAGER__LOCK_KEY retention_manager_lock Lock key for the manager in Redis retention_manager:interval RETENTION_MANAGER__INTERVAL 60000 Interval to check items to be deleted (in ms) - - - - notification_manager:enabled NOTIFICATION_MANAGER__ENABLED <code>true</code> Enable/disable the notification manager notification_manager:lock_live_key NOTIFICATION_MANAGER__LOCK_LIVE_KEY notification_live_manager_lock Lock live key for the manager in Redis notification_manager:lock_digest_key NOTIFICATION_MANAGER__LOCK_DIGEST_KEY notification_digest_manager_lock Lock digest key for the manager in Redis notification_manager:interval NOTIFICATION_MANAGER__INTERVAL 10000 Interval to push notifications - - - - publisher_manager:enabled PUBLISHER_MANAGER__ENABLED <code>true</code> Enable/disable the publisher manager publisher_manager:lock_key PUBLISHER_MANAGER__LOCK_KEY publisher_manager_lock Lock key for the manager in Redis publisher_manager:interval PUBLISHER_MANAGER__INTERVAL 10000 Interval to send notifications / digests (in ms) - - - - ingestion_manager:enabled INGESTION_MANAGER__ENABLED <code>true</code> Enable/disable the ingestion manager ingestion_manager:lock_key INGESTION_MANAGER__LOCK_KEY ingestion_manager_lock Lock key for the manager in Redis ingestion_manager:interval INGESTION_MANAGER__INTERVAL 300000 Interval to check for new data in remote feeds - - - - playbook_manager:enabled PLAYBOOK_MANAGER__ENABLED <code>true</code> Enable/disable the playbook manager playbook_manager:lock_key PLAYBOOK_MANAGER__LOCK_KEY publisher_manager_lock Lock key for the manager in Redis playbook_manager:interval PLAYBOOK_MANAGER__INTERVAL 60000 Interval to check new playbooks - - - - activity_manager:enabled ACTIVITY_MANAGER__ENABLED <code>true</code> Enable/disable the activity manager activity_manager:lock_key ACTIVITY_MANAGER__LOCK_KEY activity_manager_lock Lock key for the manager in Redis - - - - connector_manager:enabled CONNECTOR_MANAGER__ENABLED <code>true</code> Enable/disable the connector manager connector_manager:lock_key CONNECTOR_MANAGER__LOCK_KEY connector_manager_lock Lock key for the manager in Redis connector_manager:works_day_range CONNECTOR_MANAGER__WORKS_DAY_RANGE 7 Days range before considering the works as too old connector_manager:interval CONNECTOR_MANAGER__INTERVAL 10000 Interval to check the state of the works - - - - import_csv_built_in_connector:enabled IMPORT_CSV_CONNECTOR__ENABLED <code>true</code> Enable/disable the csv import connector import_csv_built_in_connector:validate_before_import IMPORT_CSV_CONNECTOR__VALIDATE_BEFORE_IMPORT <code>false</code> Validates the bundle before importing - - - - file_index_manager:enabled FILE_INDEX_MANAGER__ENABLED <code>true</code> Enable/disable the file indexing manager file_index_manager:stream_lock_key FILE_INDEX_MANAGER__STREAM_LOCK file_index_manager_stream_lock Stream lock key for the manager in Redis file_index_manager:interval FILE_INDEX_MANAGER__INTERVAL 60000 Interval to check for new files - - - - indicator_decay_manager:enabled INDICATOR_DECAY_MANAGER__ENABLED <code>true</code> Enable/disable the indicator decay manager indicator_decay_manager:lock_key INDICATOR_DECAY_MANAGER__LOCK_KEY indicator_decay_manager_lock Lock key for the manager in Redis indicator_decay_manager:interval INDICATOR_DECAY_MANAGER__INTERVAL 60000 Interval to check for indicators to update indicator_decay_manager:batch_size INDICATOR_DECAY_MANAGER__BATCH_SIZE 10000 Number of indicators handled by the manager - - - - garbage_collection_manager:enabled GARBAGE_COLLECTION_MANAGER__ENABLED <code>true</code> Enable/disable the trash manager garbage_collection_manager:lock_key GARBAGE_COLLECTION_MANAGER__LOCK_KEY garbage_collection_manager_lock Lock key for the manager in Redis garbage_collection_manager:interval GARBAGE_COLLECTION_MANAGER__INTERVAL 60000 Interval to check for trash elements to delete garbage_collection_manager:batch_size GARBAGE_COLLECTION_MANAGER__BATCH_SIZE 10000 Number of trash elements to delete at once garbage_collection_manager:deleted_retention_days GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS 7 Days after which elements in trash are deleted - - - - telemetry_manager:lock_key TELEMETRY_MANAGER__LOCK_LOCK telemetry_manager_lock Lock key for the manager in Redis <p>Manager's duties</p> <p>A description of each manager's duties is available on a dedicated page.</p>"},{"location":"deployment/configuration/#worker-and-connector","title":"Worker and connector","text":"<p>Can be configured manually using the configuration file <code>config.yml</code> or through environment variables.</p> Parameter Environment variable Default value Description opencti:url OPENCTI_URL The URL of the OpenCTI platform opencti:token OPENCTI_TOKEN A token of an administrator account with bypass capability - - - - mq:use_ssl / / Depending of the API configuration (fetch from API) mq:use_ssl_ca MQ_USE_SSL_CA Path or ca content mq:use_ssl_cert MQ_USE_SSL_CERT Path or cert content mq:use_ssl_key MQ_USE_SSL_KEY Path or key content mq:use_ssl_passphrase MQ_USE_SSL_PASSPHRASE Passphrase for the key certificate mq:use_ssl_reject_unauthorized MQ_USE_SSL_REJECT_UNAUTHORIZED <code>false</code> Reject rabbit self signed certificate"},{"location":"deployment/configuration/#worker-specific-configuration","title":"Worker specific configuration","text":""},{"location":"deployment/configuration/#logging_1","title":"Logging","text":"Parameter Environment variable Default value Description worker:log_level WORKER_LOG_LEVEL info The log level (error, warning, info or debug)"},{"location":"deployment/configuration/#telemetry_1","title":"Telemetry","text":"Parameter Environment variable Default value Description worker:telemetry_enabled WORKER_TELEMETRY_ENABLED false Enable the Prometheus endpoint worker:telemetry_prometheus_port WORKER_PROMETHEUS_TELEMETRY_PORT 14270 Port of the Prometheus endpoint worker:telemetry_prometheus_host WORKER_PROMETHEUS_TELEMETRY_HOST 0.0.0.0 Listen address of the Prometheus endpoint"},{"location":"deployment/configuration/#connector-specific-configuration","title":"Connector specific configuration","text":"<p>For specific connector configuration, you need to check each connector behavior.</p>"},{"location":"deployment/configuration/#elasticsearch_1","title":"ElasticSearch","text":"<p>If you want to adapt the memory consumption of ElasticSearch, you can use these options:</p> <pre><code># Add the following environment variable:\n\"ES_JAVA_OPTS=-Xms8g -Xmx8g\"\n</code></pre> <p>This can be done in configuration file in the <code>jvm.conf</code> file.</p>"},{"location":"deployment/connectors/","title":"Connectors","text":""},{"location":"deployment/connectors/#introduction","title":"Introduction","text":"<p>Connectors list</p> <p>You are looking for the available connectors? The list is in the OpenCTI Ecosystem.</p> <p>Connectors are the cornerstone of the OpenCTI platform and allow organizations to easily ingest, enrich or export data. According to their functionality and use case, they are categorized in the following classes.</p> <p></p>"},{"location":"deployment/connectors/#import","title":"Import","text":"<p>These connectors automatically retrieve information from an external organization, application, or service, and convert it to STIX 2.1 bundles. Then, they import it into OpenCTI using the workers.</p>"},{"location":"deployment/connectors/#enrichment","title":"Enrichment","text":"<p>When a new object is created in the platform or on the user request, it is possible to trigger the internal enrichment connector to lookup and/or search the object in external organizations, applications, or services. If the object is found, the connectors will generate a STIX 2.1 bundle which will increase the level of knowledge about the concerned object.</p> <p></p>"},{"location":"deployment/connectors/#stream","title":"Stream","text":"<p>These connectors connect to a platform live stream and continuously do something with the received events. In most cases, they are used to consume OpenCTI data and insert them in third-party platforms such as SIEMs, XDRs, EDRs, etc. In some cases, stream connectors can also query the external system on a regular basis and act as import connector for instance to gather alerts and sightings related to CTI data and push them to OpenCTI (bi-directional).</p>"},{"location":"deployment/connectors/#import-files","title":"Import files","text":"<p>Information from an uploaded file can be extracted and ingested into OpenCTI. Examples are files attached to a report or a STIX 2.1 file.</p>"},{"location":"deployment/connectors/#export-files","title":"Export files","text":"<p>Information stored in OpenCTI can be extracted into different file formats like .csv or .json (STIX 2.1).</p>"},{"location":"deployment/connectors/#connector-configuration","title":"Connector configuration","text":""},{"location":"deployment/connectors/#connector-users-and-tokens","title":"Connector users and tokens","text":"<p>All connectors have to be able to access the OpenCTI API. To allow this connection, they have 2 mandatory configuration parameters, the <code>OPENCTI_URL</code> and the <code>OPENCTI_TOKEN</code>.</p> <p>Connectors tokens</p> <p>Be careful, we strongly recommend to use a dedicated token for each connector running in the platform. So you have to create a specific user for each of them.</p> <p>Also, if all connectors users can run in with a user belonging to the <code>Connectors</code> group (with the <code>Connector</code> role), the <code>Internal Export Files</code> should be run with a user who is Administrator (with bypass capability) because they impersonate the user requesting the export to avoid data leak.</p> Type Required role Used permissions EXTERNAL_IMPORT Connector Import data with the connector user. INTERNAL_ENRICHMENT Connector Enrich data with the connector user. INTERNAL_IMPORT_FILE Connector Import data with the connector user. INTERNAL_EXPORT_FILE Administrator Export data with the user who requested the export. STREAM Connector Consume the streams with the connector user."},{"location":"deployment/connectors/#parameters","title":"Parameters","text":"<p>In addition to these 2 parameters, connectors have other mandatory parameters that need to be set in order to get them work.</p> <p>Here is an example of a connector <code>docker-compose.yml</code> file: <pre><code>- CONNECTOR_ID=ChangeMe\n- CONNECTOR_TYPE=EXTERNAL_IMPORT\n- CONNECTOR_NAME=MITRE ATT&amp;CK\n- CONNECTOR_SCOPE=identity,attack-pattern,course-of-action,intrusion-set,malware,tool,report\n- CONNECTOR_LOG_LEVEL=info\n</code></pre></p> <p>Here is an example in a connector <code>config.yml</code> file:</p> <pre><code>connector:\n  id: 'ChangeMe'\n  type: 'EXTERNAL_IMPORT'\n  name: 'MITRE ATT&amp;CK'\n  scope: 'identity,attack-pattern,course-of-action,intrusion-set,malware,tool,report'\n  log_level: 'info'\n</code></pre>"},{"location":"deployment/connectors/#advanced-parameters","title":"Advanced parameters","text":"<p>By default, connector are connecting to <code>RabbitMQ</code> using parameters and credentials directly given by the API during the connector registration process. In some cases, you may need to override them.</p> <pre><code>- MQ_HOST=rabbit.mydomain.com\n- MQ_PORT=5672\n- MQ_VHOST=/\n- MQ_USE_SSL=false\n- MQ_USER=guest\n- MQ_PASS=guest\n</code></pre> <p>Here is an example in a connector <code>config.yml</code> file:</p> <pre><code>mq:\n  host: 'rabbit.mydomain.com'\n  port: '5672'\n  use_ssl: false\n  user: 'guest'\n  pass: 'guest'\n</code></pre>"},{"location":"deployment/connectors/#networking","title":"Networking","text":"<p>Be aware that all connectors are reaching RabbitMQ based the RabbitMQ configuration provided by the OpenCTI platform. The connector must be able to reach RabbitMQ on the specified hostname and port. If you have a specific Docker network configuration, please be sure to adapt your <code>docker-compose.yml</code> file in such way that the connector container gets attached to the OpenCTI Network, e.g.:</p> <pre><code>networks:\n  default:\n    external: true\n    name: opencti-docker_default\n</code></pre> <p></p>"},{"location":"deployment/connectors/#connector-token","title":"Connector token","text":""},{"location":"deployment/connectors/#create-the-user","title":"Create the user","text":"<p>As mentioned previously, it is strongly recommended to run each connector with its own user. The <code>Internal Export File</code> connectors should be launched with a user that belongs to a group which has an \u201cAdministrator\u201d role (with bypass all capabilities enabled).</p> <p>By default, in platform, a group named \"Connectors\" already exists. So just create a new user with the name <code>[C] Name of the connector</code> in Settings &gt; Security &gt; Users.</p> <p></p>"},{"location":"deployment/connectors/#put-the-user-in-the-group","title":"Put the user in the group","text":"<p>Just go to the user you have just created and add it to the <code>Connectors</code> group.</p> <p></p> <p>Then just get the token of the user displayed in the interface.</p> <p></p>"},{"location":"deployment/connectors/#docker-activation","title":"Docker activation","text":"<p>You can either directly run the Docker image of connectors or add them to your current <code>docker-compose.yml</code> file.</p>"},{"location":"deployment/connectors/#add-a-connector-to-your-deployment","title":"Add a connector to your deployment","text":"<p>For instance, to enable the MISP connector, you can add a new service to your <code>docker-compose.yml</code> file:</p> <pre><code>  connector-misp:\n    image: opencti/connector-misp:latest\n    environment:\n      - OPENCTI_URL=http://localhost\n      - OPENCTI_TOKEN=ChangeMe\n      - CONNECTOR_ID=ChangeMe\n      - CONNECTOR_TYPE=EXTERNAL_IMPORT\n      - CONNECTOR_NAME=MISP\n      - CONNECTOR_SCOPE=misp\n      - CONNECTOR_LOG_LEVEL=info\n      - MISP_URL=http://localhost # Required\n      - MISP_KEY=ChangeMe # Required\n      - MISP_SSL_VERIFY=False # Required\n      - MISP_CREATE_REPORTS=True # Required, create report for MISP event\n      - MISP_REPORT_CLASS=MISP event # Optional, report_class if creating report for event\n      - MISP_IMPORT_FROM_DATE=2000-01-01 # Optional, import all event from this date\n      - MISP_IMPORT_TAGS=opencti:import,type:osint # Optional, list of tags used for import events\n      - MISP_INTERVAL=1 # Required, in minutes\n    restart: always\n</code></pre>"},{"location":"deployment/connectors/#launch-a-standalone-connector","title":"Launch a standalone connector","text":"<p>To launch standalone connector, you can use the <code>docker-compose.yml</code> file of the connector itself. Just download the latest release and start the connector:</p> <pre><code>$ wget https://github.com/OpenCTI-Platform/connectors/archive/{RELEASE_VERSION}.zip\n$ unzip {RELEASE_VERSION}.zip\n$ cd connectors-{RELEASE_VERSION}/misp/\n</code></pre> <p>Change the configuration in the <code>docker-compose.yml</code> according to the parameters of the platform and of the targeted service. Then launch the connector:</p> <pre><code>$ docker-compose up\n</code></pre>"},{"location":"deployment/connectors/#manual-activation","title":"Manual activation","text":"<p>If you want to manually launch connector, you just have to install Python 3 and pip3 for dependencies:</p> <pre><code>$ apt install python3 python3-pip\n</code></pre> <p>Download the release of the connectors:</p> <pre><code>$ wget &lt;https://github.com/OpenCTI-Platform/connectors/archive/{RELEASE_VERSION}.zip&gt;\n$ unzip {RELEASE_VERSION}.zip\n$ cd connectors-{RELEASE_VERSION}/misp/src/\n</code></pre> <p>Install dependencies and initialize the configuration:</p> <pre><code>$ pip3 install -r requirements.txt\n$ cp config.yml.sample config.yml\n</code></pre> <p>Change the <code>config.yml</code> content according to the parameters of the platform and of the targeted service and launch the connector:</p> <pre><code>$ python3 misp.py\n</code></pre>"},{"location":"deployment/connectors/#connectors-status","title":"Connectors status","text":"<p>The connector status can be displayed in the dedicated section of the platform available in Data &gt; Ingestion &gt; Connectors. You will be able to see the statistics of the RabbitMQ queue of the connector:</p> <p></p> <p>Problem</p> <p>If you encounter problems deploying OpenCTI or connectors, you can consult the troubleshooting page page.</p>"},{"location":"deployment/installation/","title":"Installation","text":"<p>All components of OpenCTI are shipped both as Docker images and manual installation packages.</p> <p>Production deployment</p> <p>For production deployment, we recommend to deploy all components in containers, including dependencies, using native cloud services or orchestration systems such as Kubernetes.</p> <p>To have more details about deploying OpenCTI and its dependencies in cluster mode, please read the dedicated section.</p> <ul> <li> <p> Use Docker</p> <p>Deploy OpenCTI using Docker and the default <code>docker-compose.yml</code> provided in the docker.</p> <p> Setup</p> </li> <li> <p> Manual installation</p> <p>Deploy dependencies and launch the platform manually using the packages released in the GitHub releases.</p> <p> Explore</p> </li> </ul>"},{"location":"deployment/installation/#using-docker","title":"Using Docker","text":"<p>OpenCTI can be deployed using the docker-compose command.</p> <p>Deploy FIPS 140-2 compliant components</p> <p>We are providing FIPS 140-2 compliant images, please read the dedicated documentation to understand how to deploy OpenCTI in FIPS-compliant mode.</p>"},{"location":"deployment/installation/#pre-requisites","title":"Pre-requisites","text":"<p> Linux</p> <pre><code>sudo apt install docker-compose\n</code></pre> <p> Windows and MacOS</p> <p>Just download the appropriate Docker for Desktop version for your operating system.</p>"},{"location":"deployment/installation/#clone-the-repository","title":"Clone the repository","text":"<p>Docker helpers are available in the Docker GitHub repository.</p> <pre><code>mkdir -p /path/to/your/app &amp;&amp; cd /path/to/your/app\ngit clone https://github.com/OpenCTI-Platform/docker.git\ncd docker\n</code></pre>"},{"location":"deployment/installation/#configure-the-environment","title":"Configure the environment","text":"<p>ElasticSearch / OpenSearch configuration</p> <ul> <li>We highly recommend to put the ElasticSearch / OpenSearch following parameter:</li> </ul> <pre><code>thread_pool.search.queue_size=5000\n</code></pre> <ul> <li>Check the OpenCTI Integration User Permissions in OpenSearch/ElasticSearch for detailed information about the necessary user permissions for the OpenSearch/ElasticSearch integration.</li> </ul> <p>Before running the <code>docker-compose</code> command, the <code>docker-compose.yml</code> file should be configured. By default, the <code>docker-compose.yml</code> file is using environment variables available in the file <code>.env.sample</code>.</p> <p>You can either rename the file <code>.env.sample</code> in <code>.env</code> and put the expected values or just fill directly the <code>docker-compose.yml</code> with the values corresponding to your environment.</p> <p>Configuration static parameters</p> <p>The complete list of available static parameters is available in the configuration section.</p> <p>Here is an example to quickly generate the <code>.env</code> file under Linux, especially all the default UUIDv4:</p> <pre><code>sudo apt install -y jq\ncd ~/docker\n(cat &lt;&lt; EOF\nOPENCTI_ADMIN_EMAIL=admin@opencti.io\nOPENCTI_ADMIN_PASSWORD=ChangeMePlease\nOPENCTI_ADMIN_TOKEN=$(cat /proc/sys/kernel/random/uuid)\nOPENCTI_BASE_URL=http://localhost:8080\nMINIO_ROOT_USER=$(cat /proc/sys/kernel/random/uuid)\nMINIO_ROOT_PASSWORD=$(cat /proc/sys/kernel/random/uuid)\nRABBITMQ_DEFAULT_USER=guest\nRABBITMQ_DEFAULT_PASS=guest\nELASTIC_MEMORY_SIZE=4G\nCONNECTOR_HISTORY_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_STIX_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_CSV_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_IMPORT_FILE_STIX_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_TXT_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_IMPORT_DOCUMENT_ID=$(cat /proc/sys/kernel/random/uuid)\nSMTP_HOSTNAME=localhost\nEOF\n) &gt; .env\n</code></pre> <p>If your <code>docker-compose</code> deployment does not support <code>.env</code> files, just export all environment variables before launching the platform:</p> <pre><code>export $(cat .env | grep -v \"#\" | xargs)\n</code></pre> <p>As OpenCTI has a dependency on ElasticSearch, you have to set the <code>vm.max_map_count</code> before running the containers, as mentioned in the ElasticSearch documentation.</p> <pre><code>sudo sysctl -w vm.max_map_count=1048575\n</code></pre> <p>To make this parameter persistent, add the following to the end of your <code>/etc/sysctl.conf</code>:</p> <pre><code>vm.max_map_count=1048575\n</code></pre>"},{"location":"deployment/installation/#persist-data","title":"Persist data","text":"<p>The default for OpenCTI data is to be persistent.</p> <p>In the <code>docker-compose.yml</code>, you will find at the end the list of necessary persistent volumes for the dependencies:</p> <pre><code>volumes:\n  esdata:     # ElasticSearch data\n  s3data:     # S3 bucket data\n  redisdata:  # Redis data\n  amqpdata:   # RabbitMQ data\n</code></pre>"},{"location":"deployment/installation/#run-opencti","title":"Run OpenCTI","text":""},{"location":"deployment/installation/#using-single-node-docker","title":"Using single node Docker","text":"<p>After changing your <code>.env</code> file run <code>docker-compose</code> in detached (-d) mode:</p> <pre><code>sudo systemctl start docker.service\n# Run docker-compose in detached\ndocker-compose up -d\n</code></pre>"},{"location":"deployment/installation/#using-docker-swarm","title":"Using Docker swarm","text":"<p>In order to have the best experience with Docker, we recommend using the Docker stack feature. In this mode you will have the capacity to easily scale your deployment.</p> <pre><code># If your virtual machine is not a part of a Swarm cluster, please use:\ndocker swarm init\n</code></pre> <p>Put your environment variables in <code>/etc/environment</code>:</p> <pre><code># If you already exported your variables to .env from above:\nsudo cat .env &gt;&gt; /etc/environment\nsudo bash -c 'cat .env &gt;&gt; /etc/environment'\nsudo docker stack deploy --compose-file docker-compose.yml opencti\n</code></pre> <p>Installation done</p> <p>You can now go to http://localhost:8080 and log in with the credentials configured in your environment variables.</p>"},{"location":"deployment/installation/#manual-installation","title":"Manual installation","text":""},{"location":"deployment/installation/#prerequisites","title":"Prerequisites","text":""},{"location":"deployment/installation/#installation-of-dependencies","title":"Installation of dependencies","text":"<p>You have to install all the needed dependencies for the main application and the workers. The example below is for Debian-based systems:</p> <pre><code>sudo apt-get update\nsudo apt-get install build-essential nodejs npm python3 python3-pip python3-dev\n</code></pre>"},{"location":"deployment/installation/#download-the-application-files","title":"Download the application files","text":"<p>First, you have to download and extract the latest release file. Then select the version to install depending of your operating system:</p> <p>For Linux:</p> <ul> <li>If your OS supports libc (Ubuntu, Debian, ...) you have to install the <code>opencti-release_{RELEASE_VERSION}.tar.gz</code> version.</li> <li>If your OS uses musl (Alpine, ...) you have to install the <code>opencti-release-{RELEASE_VERSION}_musl.tar.gz</code> version.</li> </ul> <p>For Windows:</p> <p>We don't provide any Windows release for now. However it is still possible to check the code out, manually install the dependencies and build the software.</p> <pre><code>mkdir /path/to/your/app &amp;&amp; cd /path/to/your/app\nwget &lt;https://github.com/OpenCTI-Platform/opencti/releases/download/{RELEASE_VERSION}/opencti-release-{RELEASE_VERSION}.tar.gz&gt;\ntar xvfz opencti-release-{RELEASE_VERSION}.tar.gz\n</code></pre>"},{"location":"deployment/installation/#install-the-main-platform","title":"Install the main platform","text":""},{"location":"deployment/installation/#configure-the-application","title":"Configure the application","text":"<p>The main application has just one JSON configuration file to change and a few Python modules to install</p> <pre><code>cd opencti\ncp config/default.json config/production.json\n</code></pre> <p>Change the config/production.json file according to your configuration of ElasticSearch, Redis, RabbitMQ and S3 bucket as well as default credentials (the <code>ADMIN_TOKEN</code> must be a valid UUID).</p>"},{"location":"deployment/installation/#install-the-python-modules","title":"Install the Python modules","text":"<pre><code>cd src/python\npip3 install -r requirements.txt\ncd ../..\n</code></pre>"},{"location":"deployment/installation/#start-the-application","title":"Start the application","text":"<p>The application is just a NodeJS process, the creation of the database schema and the migration will be done at starting.</p> <p>Please verify that yarn version is greater than 4 and node version is greater or equals to v19. Please note that some Node.js version are outdated in linux package manager, you can download a recent one in https://nodejs.org/en/download or alternatively nvm can help to chose a recent version of Node.js https://github.com/nvm-sh/nvm</p> <pre><code>yarn --version\n#4.1.0\nnode --version\n#v20.11.1\n</code></pre> <p>Once Node.js is setup, you can build and run with (from inside <code>opencti</code> folder): <pre><code>yarn install\nyarn build\nyarn serv\n</code></pre></p> <p>The default username and password are those you have put in the <code>config/production.json</code> file.</p>"},{"location":"deployment/installation/#install-the-worker","title":"Install the worker","text":"<p>The OpenCTI worker is used to write the data coming from the RabbitMQ messages broker.</p>"},{"location":"deployment/installation/#configure-the-worker","title":"Configure the worker","text":"<pre><code>cd worker\npip3 install -r requirements.txt\ncp config.yml.sample config.yml\n</code></pre> <p>Change the config.yml file according to your OpenCTI token.</p>"},{"location":"deployment/installation/#start-as-many-workers-as-you-need","title":"Start as many workers as you need","text":"<pre><code>python3 worker.py &amp;\npython3 worker.py &amp;\n</code></pre> <p>Installation done</p> <p>You can now go to http://localhost:4000 and log in with the credentials configured in your <code>production.json</code> file.</p>"},{"location":"deployment/installation/#community-contributions","title":"Community contributions","text":""},{"location":"deployment/installation/#terraform","title":"Terraform","text":"<ul> <li> <p> Multi-clouds Terraform scripts</p> <p>This repository is here to provide you with a quick and easy way to deploy an OpenCTI instance in the cloud (AWS, Azure, or GCP).</p> <p> GitHub Respository</p> </li> <li> <p> AWS Advanced Terraform scripts</p> <p>A Terraform deployment of OpenCTI designed to make use of native AWS Resources (where feasible). This includes AWS ECS Fargate, AWS OpenSearch, etc.</p> <p> GitHub Repository</p> </li> </ul>"},{"location":"deployment/installation/#helm-charts","title":"Helm Charts","text":"<ul> <li> <p> Kubernetes Helm Charts</p> <p>OpenCTI Helm Charts for Kubernetes with a global configuration file. More information how to deploy here on basic installation and examples.</p> <p> GitHub Repository</p> </li> </ul>"},{"location":"deployment/installation/#deploy-behind-a-reverse-proxy","title":"Deploy behind a reverse proxy","text":"<p>If you want to use OpenCTI behind a reverse proxy with a context path, like <code>https://domain.com/opencti</code>, please change the <code>base_path</code> static parameter.</p> <ul> <li><code>APP__BASE_PATH=/opencti</code></li> </ul> <p>By default OpenCTI use websockets so don't forget to configure your proxy for this usage, an example with <code>Nginx</code>:</p> <pre><code>location / {\n    proxy_cache                 off;\n    proxy_buffering             off;\n    proxy_http_version          1.1;\n    proxy_set_header Upgrade    $http_upgrade;\n    proxy_set_header Connection \"upgrade\";\n    proxy_set_header Host       $host;\n    chunked_transfer_encoding   off;\n    proxy_pass                  http://YOUR_UPSTREAM_BACKEND;\n  }\n</code></pre>"},{"location":"deployment/installation/#additional-memory-information","title":"Additional memory information","text":""},{"location":"deployment/installation/#platform","title":"Platform","text":"<p>OpenCTI platform is based on a NodeJS runtime, with a memory limit of 8GB by default. If you encounter <code>OutOfMemory</code> exceptions, this limit could be changed:</p> <pre><code>- NODE_OPTIONS=--max-old-space-size=8096\n</code></pre>"},{"location":"deployment/installation/#workers-and-connectors","title":"Workers and connectors","text":"<p>OpenCTI workers and connectors are Python processes. If you want to limit the memory of the process, we recommend to directly use Docker to do that. You can find more information in the official Docker documentation.</p>"},{"location":"deployment/installation/#elasticsearch","title":"ElasticSearch","text":"<p>ElasticSearch is also a JAVA process. In order to setup the JAVA memory allocation, you can use the environment variable <code>ES_JAVA_OPTS</code>. You can find more information in the official ElasticSearch documentation.</p>"},{"location":"deployment/installation/#redis","title":"Redis","text":"<p>Redis has a very small footprint on keys but will consume memory for the stream. By default the size of the stream is limited to 2 millions which represents a memory footprint around <code>8 GB</code>. You can find more information in the Redis docker hub.</p>"},{"location":"deployment/installation/#minio-s3-bucket","title":"MinIO / S3 Bucket","text":"<p>MinIO is a small process and does not require a high amount of memory. More information are available for Linux here on the Kernel tuning guide.</p>"},{"location":"deployment/installation/#rabbitmq","title":"RabbitMQ","text":"<p>The RabbitMQ memory configuration can be find in the RabbitMQ official documentation. RabbitMQ will consumed memory until a specific threshold, therefore it should be configure along with the Docker memory limitation.</p>"},{"location":"deployment/integrations/","title":"Integrations","text":""},{"location":"deployment/integrations/#introduction","title":"Introduction","text":"<p>OpenCTI supports multiple ways to integrate with other systems which do not have native connectors or plugins to the platform. Here are the technical features available to ease the connection and the integration of the platform with other applications.</p> <p>Connectors list</p> <p>If you are looking for the list of OpenCTI connectors or native integration, please check the OpenCTI Ecosystem.</p>"},{"location":"deployment/integrations/#native-feeds-and-streams","title":"Native feeds and streams","text":"<p>To ease integrations with other products, OpenCTI has built-in capabilities to deliver the data to third-parties.</p>"},{"location":"deployment/integrations/#csv-feeds","title":"CSV Feeds","text":"<p>It is possible to create as many CSV feeds as needed, based on filters and accessible in HTTP. CSV feeds are available in Data &gt; Data sharing &gt; CSV deeds.</p> <p>When creating a CSV feed, you need to select one or multiple types of entities to make available. Then, you must assign a field (of an entity type) to each column in the CSV:</p> <p></p> <p>Details</p> <p>For more information about CSV feeds, filters and configuration, please check the Native feeds page.</p>"},{"location":"deployment/integrations/#taxii-collections","title":"TAXII collections","text":"<p>Most of the modern cybersecurity systems such as SIEMs, EDRs, XDRs and even firewalls supports the TAXII protocol which is basically a paginated HTTP STIX feed. OpenCTI implements a TAXII 2.1 server with the ability to create as many TAXII collections as needed in Data &gt; Data sharing &gt; TAXII Collections.</p> <p>TAXII collections are a sub-selection of the knowledge available in the platform and rely on filters. For instance, it is possible to create TAXII collections for pieces of malware with a given label, for indicators with a score greater than n, etc.</p> <p></p>"},{"location":"deployment/integrations/#live-streams","title":"Live Streams","text":"<p>After implementing CSV feeds and TAXII collections, we figured out that those 2 stateless APIs are definitely not enough when it comes to tackle advanced information sharing challenges such as:</p> <ul> <li>Real time transmission of the information (i.e. avoid hundreds of systems to pull data every 5 minutes).</li> <li>Dependencies resolution (i.e. an intrusion created by an organization but the organization is not in the TAXII collection).</li> <li>Partial update for huge entities such as report (i.e. just having the update event).</li> <li>Delete events when necessary (i.e. to handle indicators expiration in third party systems for instance).</li> </ul> <p>That's why we've developed the live streams. They are available in Data &gt; Data sharing &gt; Live streams. As TAXII collections, it is possible to create as many streams as needed using filters.</p> <p></p> <p>Streams implement the HTTP SSE (Server-sent events) protocol and give applications the possibility to consume a real time pure STIX 2.1 stream. Stream connectors in the OpenCTI Ecosystem are using live streams to consume data and do something such as create / update / delete information in SIEMs, XDRs, etc.</p>"},{"location":"deployment/integrations/#authentication","title":"Authentication","text":"<p>For all previously explained capabilities, as they are over the HTTP protocol, 3 authentication mechanisms are available to consume them.</p> <ol> <li> <p>Using a bearer header with your OpenCTI API key</p> <pre><code>Authorization: Bearer a17bc103-8420-4208-bd53-e1f80845d15f\n</code></pre> <p>API Key</p> <p>Your API key can be found in your profile available clicking on the top right icon.</p> </li> <li> <p>Using basic authentication</p> <pre><code>Username: Your platform username\nPassword: Your plafrom password\nAuthorization: Basic c2FtdWVsLmhhc3NpbmVBZmlsaWdyYW4uaW86TG91aXNlMTMwNCM=\n</code></pre> </li> <li> <p>Using client certificate authentication</p> <p>To know how to configure the client certificate authentication, please consult the authentication configuration section.</p> </li> </ol>"},{"location":"deployment/integrations/#api-and-libraries","title":"API and libraries","text":""},{"location":"deployment/integrations/#graphql-api","title":"GraphQL API","text":"<p>To allow analysts and developers to implement more custom or complex use cases, a full GraphQL API is available in the application on the <code>/graphql</code> endpoint.</p> <p>The API can be queried using various GraphQL client such as Postman but you can leverage any HTTP client to forge GraphQL queries using <code>POST</code> methods.</p>"},{"location":"deployment/integrations/#authentication_1","title":"Authentication","text":"<p>The API authentication can be performed using the token of a user and a classic Authorization header:</p> <pre><code>Content-Type: application/json\nAuthorization: Bearer 6b6554c4-bb2c-4c80-9cd3-30288c8bf424\n</code></pre>"},{"location":"deployment/integrations/#playground","title":"Playground","text":"<p>The playground is available on the <code>/graphql</code> endpoint. A link button is also available in the profile of your user.</p> <p></p> <p>All the schema documentation is directly available in the playground.</p> <p></p> <p>If you already logged to OpenCTI with the same browser you should be able to directly do some requests. If you are not authenticated or want to authenticate only through the playground you can use a header configuration using your profile token</p> <p>Example of configuration (bottom left of the playground):</p> <p></p> <p>Additional GraphQL documentation</p> <p>To find out more about GraphQL and the playground, you can find two additional documentation pages: the GraphQL API page and the GraphQL playground page.</p>"},{"location":"deployment/integrations/#python-library","title":"Python library","text":"<p>Since not everyone is familiar with GraphQL APIs, we've developed a Python library to ease the interaction with it. The library is pretty easy to use. To initiate the client:</p> <pre><code># coding: utf-8\n\nfrom pycti import OpenCTIApiClient\n\n# Variables\napi_url = \"http://opencti:4000\"\napi_token = \"bfa014e0-e02e-4aa6-a42b-603b19dcf159\"\n\n# OpenCTI initialization\nopencti_api_client = OpenCTIApiClient(api_url, api_token)\n</code></pre> <p>Then just use the available helpers: <pre><code># Search for malware with the keyword \"windows\"\nmalwares = opencti_api_client.malware.list(search=\"windows\")\n\n# Print\nprint(malwares)\n</code></pre></p> <p>Details</p> <p>For more detailed information about the Python library, please read the dedicated section.</p>"},{"location":"deployment/managers/","title":"Platform managers","text":"<p>Platform managers are background components that perform various tasks to support some important functionalities in the platform.</p> <p>Here is a list of all the managers on the platform:</p>"},{"location":"deployment/managers/#rules-engine","title":"Rules engine","text":"<p>Allows users to execute pre-defined actions based on the data and events in the platform.</p> <p>These rules are accessible in Settings &gt; Customization &gt; Rules engine.</p> <p>The rules engine is designed to help users automate and streamline their cyber threat intelligence processes.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#history-manager","title":"History manager","text":"<p>This manager keeps tracks of user/connector interactions on entities in the platform.</p> <p>It is designed to help users audit and understand the evolution of their CTI data.</p>"},{"location":"deployment/managers/#activity-manager","title":"Activity manager","text":"<p>The activity manager in OpenCTI is a component that monitors and logs the user actions in the platform such as login, settings update, and user activities if configured (read, udpate, etc.).</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#background-task-manager","title":"Background task manager","text":"<p>Is a component that handles the execution of tasks, such as importing data, exporting data and mass operations.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#expiration-scheduler","title":"Expiration scheduler","text":"<p>The expiration scheduler is responsible for monitoring expired elements in the platform. It cancels the access rights of expired user accounts and revokes expired indicators from the platform.</p>"},{"location":"deployment/managers/#synchronization-manager","title":"Synchronization manager","text":"<p>The synchronization manager enables the data sharing between multiple OpenCTI platforms.  It allows the user to create and configure synchronizers which are processes that connect to the live streams of remote OpenCTI platforms and import the data into the local platform. </p>"},{"location":"deployment/managers/#retention-manager","title":"Retention manager","text":"<p>The retention manager is a component that allows the user to define rules to help delete data in OpenCTI that is no longer relevant or useful. This helps to optimize the performance and storage of the OpenCTI platform and ensures the quality and accuracy of the data.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#notification-manager","title":"Notification manager","text":"<p>The notification manager is a component that allows the user to customize and receive alerts about events/changes in the platform.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#ingestion-manager","title":"Ingestion manager","text":"<p>The ingestion manager in OpenCTI is a component that manages the ingestion of data from RSS and TAXII feeds.</p>"},{"location":"deployment/managers/#playbook-manager","title":"Playbook manager","text":"<p>The playbook manager handles the automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform.</p> <p>Please read the Playbook automation page to get more information.</p>"},{"location":"deployment/managers/#file-index-manager","title":"File index manager","text":"<p>The file indexing manager extracts and indexes the text content of the files, and stores it in the database. It allows users to search for text content within files uploaded to the platform.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#indicator-decay-manager","title":"Indicator decay manager","text":"<p>The indicator decay manager allows to update indicators score automatically based on configured decay rules.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#trash-manager","title":"Trash manager","text":"<p>The trash manager is responsible to delete permanently elements stored in the trash after a specified period of time (7 days by default).</p>"},{"location":"deployment/managers/#filigran-telemetry-manager","title":"Filigran telemetry manager","text":"<p>The telemetry manager collects periodically statistical data about platform usage.</p> <p>More information about data telemetry can be found here.</p>"},{"location":"deployment/map/","title":"Deploy on-premise map server with OpenCTI styles","text":""},{"location":"deployment/map/#introduction","title":"Introduction","text":"<p>The OpenStreetMap tiles for the planet will take 80GB. Here are the instructions to deploy a local OpenStreetMap server with the OpenCTI styles.</p>"},{"location":"deployment/map/#create-directory-for-the-data-and-upload-planet-data","title":"Create directory for the data and upload planet data","text":"<p>When you will launch the map server container, it will be necessary to mount a volume with the planet tiles data. Just create the directory for the data.</p> <pre><code>mkdir /var/YOUR_DATA_DIR\n</code></pre> <p>We have hosted the free-to-use planet tiles, just download the planet data from filigran.io.</p> <pre><code>wget https://filigran.io/app/uploads/maptiler-osm-2020-02-10-v3.11-planet.mbtiles\n</code></pre> <p>Put the file <code>maptiler-osm-2020-12-14-v3.11-planet.mbtiles</code> in the data directory:</p> <pre><code>cp maptiler-osm-2020-12-14-v3.11-planet.mbtiles /var/YOUR_DATA_DIR/\n</code></pre>"},{"location":"deployment/map/#start-docker","title":"Start Docker","text":"<p>Replace the port 80 by the port you would like to expose. Inside the Docker, the map server listen on the port 80.</p> <pre><code>docker run -d --restart always -v /var/YOUR_DATA_DIR:/data -p 80:80 klokantech/openmaptiles-server:latest \n</code></pre>"},{"location":"deployment/map/#configure","title":"Configure","text":"<p>Download on your computer the OpenCTI JSON styles (you will have to upload it through the web UI later).</p> <ul> <li>OpenCTI Map Dark mode style (filigran-dark2.json)</li> <li>OpenCTI Map Light mode style (filigran-light2.json)</li> </ul> <p>Now, you can access to the map server, you should see the following page:</p> <p></p> <p>On the next page, you should see the existing data:</p> <p></p> <p>On the next page, click on \"Advanced Options\":</p> <p></p> <p>Upload the <code>filigran-dark2.json</code> and <code>filigran-light2.json</code> files:</p> <p></p> <p>Save and run the server with default parameters:</p> <p></p>"},{"location":"deployment/map/#opencti-parameters","title":"OpenCTI Parameters","text":"<p>Once the server is running, you should see the list of available styles:</p> <p></p> <p>Click on \"Viewer\", and take the URL:</p> <p>\ud83d\udc49 http:/YOUR_URL/styles/{ID}/....</p> <p>In the OpenCTI configuration, just put:</p> Parameter Environment variable Value Description app:map_tile_server_dark APP__MAP_TILE_SERVER_DARK http://{YOUR_MAP_SERVER}/styles/{ID_DARK}/{z}/{x}/{y}.png The address of the OpenStreetMap provider with dark theme style app:map_tile_server_light APP__MAP_TILE_SERVER_LIGHT http://{YOUR_MAP_SERVER}/styles/{ID_LIGHT}/{z}/{x}/{y}.png The address of the OpenStreetMap provider with light theme style <p>You're good to go!</p>"},{"location":"deployment/overview/","title":"Overview","text":"<p>Before starting the installation, let's discover how OpenCTI is working, which dependencies are needed and what are the minimal requirements to deploy it in production.</p>"},{"location":"deployment/overview/#architecture","title":"Architecture","text":"<p>The OpenCTI platform relies on several external databases and services in order to work.</p> <p></p>"},{"location":"deployment/overview/#platform","title":"Platform","text":"<p>The platform is the central part of the OpenCTI technological stack. It allows users to access to the user interface but also provides the GraphQL API used by connectors and workers to insert data. In the context of a production deployment, you may need to scale horizontally and launch multiple platforms behind a load balancer connected to the same databases (ElasticSearch, Redis, S3, RabbitMQ).</p>"},{"location":"deployment/overview/#workers","title":"Workers","text":"<p>The workers are standalone Python processes consuming messages from the RabbitMQ broker in order to do asynchronous write queries. You can launch as many workers as you need to increase the write performances. At some point, the write performances will be limited by the throughput of the ElasticSearch database cluster.</p> <p>Number of workers</p> <p>If you need to increase performances, it is better to launch more platforms to handle worker queries. The recommended setup is to have at least one platform for 3 workers (ie. 9 workers distributed over 3 platforms).</p>"},{"location":"deployment/overview/#connectors","title":"Connectors","text":"<p>The connectors are third-party pieces of software (Python processes) that can play five different  roles on the platform:</p> Type Description Examples EXTERNAL_IMPORT Pull data from remote sources, convert it to STIX2 and insert it on the OpenCTI platform. MITRE Datasets, MISP, CVE, AlienVault, Mandiant, etc. INTERNAL_ENRICHMENT Listen for new OpenCTI entities or users requests, pull data from remote sources to enrich. Shodan, DomainTools, IpInfo, etc. INTERNAL_IMPORT_FILE Extract data from files uploaded on OpenCTI trough the UI or the API. STIX 2.1, PDF, Text, HTML, etc. INTERNAL_EXPORT_FILE Generate export from OpenCTI data, based on a single object or a list. STIX 2.1, CSV, PDF, etc. STREAM Consume a platform data stream an do something with events. Splunk, Elastic Security, Q-Radar, etc. <p>List of connectors</p> <p>You can find all currently available connectors in the OpenCTI Ecosystem.</p>"},{"location":"deployment/overview/#infrastructure-requirements","title":"Infrastructure requirements","text":""},{"location":"deployment/overview/#dependencies","title":"Dependencies","text":"Component Version CPU RAM Disk type Disk space ElasticSearch / OpenSearch &gt;= 8.0 / &gt;= 2.9 2 cores \u2265 8GB SSD \u2265 16GB Redis &gt;= 7.1 1 core \u2265 1GB SSD \u2265 16GB RabbitMQ &gt;= 3.11 1 core \u2265 512MB Standard \u2265 2GB S3 / MinIO &gt;= RELEASE.2023-02 1 core \u2265 128MB SSD \u2265 16GB"},{"location":"deployment/overview/#platform_1","title":"Platform","text":"Component CPU RAM Disk type Disk space OpenCTI Core 2 cores \u2265 8GB None (stateless) - Worker(s) 1 core \u2265 128MB None (stateless) - Connector(s) 1 core \u2265 128MB None (stateless) - <p>Clustering</p> <p>To have more details about deploying OpenCTI and its dependencies in cluster mode, please read the dedicated section.</p>"},{"location":"deployment/resources/","title":"Other resources","text":""},{"location":"deployment/resources/#introduction","title":"Introduction","text":"<p>OpenCTI is an open and modular platform. A lot of connectors, plugins and clients  are created by Filigran and by the community. You can find here other resources available to complete your OpenCTI journey.</p>"},{"location":"deployment/resources/#videos-training","title":"Videos &amp; training","text":"<ul> <li> <p> YouTube channel</p> <p>Watch demonstration videos, use case explanations, customers and community testimonies, and past webinars.</p> <p> Watch</p> </li> <li> <p> Training courses</p> <p>Empower your journey with OpenCTI training courses for both analyst and  administrators, and get your certificate.</p> <p> Learn</p> </li> </ul>"},{"location":"deployment/resources/#articles-news","title":"Articles &amp; news","text":"<ul> <li> <p> Blog articles</p> <p>Read posts written by both Filigran teams and community members about OpenCTI features and use cases.</p> <p> Read</p> </li> <li> <p> Newsletters</p> <p>Subscribe to Filigran newsletters to get informed about the latest evolutions of our product ecosystems.</p> <p> Subscribe</p> </li> </ul>"},{"location":"deployment/resources/#analysis","title":"Analysis","text":"<ul> <li> <p> Verticalized threat landscapes</p> <p>Access to monthly sectorial analysis from our experts team based on knowledge and data collected by our partners.</p> <p> Consult</p> </li> <li> <p> Case studies</p> <p>Explore the Filigran case studies about stories and usages of the platform  among our communities and customers.</p> <p> Download</p> </li> </ul>"},{"location":"deployment/rollover/","title":"Indices and rollover policies","text":"<p>Default rollover policies</p> <p>Since OpenCTI 5.9.0, rollover policies are automatically created when the platform is initialized for the first time. If your platform has been initialized using an older version of OpenCTI or if you would like to understand (and customize) rollover policies please read the following documentation.</p>"},{"location":"deployment/rollover/#introduction","title":"Introduction","text":"<p>ElasticSearch and OpenSearch both support rollover on indices. OpenCTI has been designed to be able to use aliases for indices and so support very well index lifecycle policies. Thus, by default OpenCTI initialized indices with a suffix <code>-00001</code> and use wildcard to query indices. When rollover policies are implemented (default starting OCTI 5.9.X if you initialized your platform at this version), indices are splitted to keep a reasonable volume of data in shards.</p> <p></p>"},{"location":"deployment/rollover/#opencti-integration-user-permissions-in-opensearchelasticsearch","title":"OpenCTI Integration User Permissions in OpenSearch/ElasticSearch","text":"<ul> <li> <p>Index Permissions</p> <ul> <li>Patterns: <code>opencti*</code> (Dependent on the parameter elasticsearch:index_prefix value)</li> <li>Permissions: <code>indices_all</code></li> </ul> </li> <li> <p>Cluster Permissions</p> <ul> <li><code>cluster_composite_ops_ro</code></li> <li><code>cluster_manage_index_templates</code></li> <li><code>cluster:admin/ingest/pipeline/put</code></li> <li><code>cluster:admin/opendistro/ism/policy/write</code></li> <li><code>cluster:monitor/health</code></li> <li><code>cluster:monitor/main</code></li> <li><code>cluster:monitor/state</code></li> <li><code>indices:admin/index_template/put</code></li> <li><code>indices:data/read/scroll/clear</code></li> <li><code>indices:data/read/scroll</code></li> <li><code>indices:data/write/bulk</code></li> </ul> </li> </ul> <p>About <code>indices:*</code> in Cluster Permissions</p> <p>It is crucial to include <code>indices:*</code> permissions in Cluster Permissions for the proper functioning of the OpenCTI integration. Removing these, even if already present in Index Permissions, may result in startup issues for the OpenCTI Platform.</p>"},{"location":"deployment/rollover/#elasticsearch-configuration","title":"ElasticSearch configuration","text":""},{"location":"deployment/rollover/#indices","title":"Indices","text":"<p>By default, a rollover policy is applied on all indices used by OpenCTI.</p> <ul> <li><code>opencti_deleted_objects</code></li> <li><code>opencti_files</code></li> <li><code>opencti_history</code></li> <li><code>opencti_inferred_entities</code></li> <li><code>opencti_inferred_relationships</code></li> <li><code>opencti_internal_objects</code></li> <li><code>opencti_internal_relationships</code></li> <li><code>opencti_stix_core_relationships</code></li> <li><code>opencti_stix_cyber_observable_relationships</code></li> <li><code>opencti_stix_cyber_observables</code></li> <li><code>opencti_stix_domain_objects</code></li> <li><code>opencti_stix_meta_objects</code></li> <li><code>opencti_stix_meta_relationships</code></li> <li><code>opencti_stix_sighting_relationships</code></li> </ul> <p>For your information, the indices which can grow rapidly are:</p> <ul> <li>Index <code>opencti_stix_meta_relationships</code>: it contains all the nested relationships between objects and labels / marking definitions / external references / authors, etc.</li> <li>Index <code>opencti_history</code>: it contains the history log of all objects in the platform.</li> <li>Index <code>opencti_stix_cyber_observables</code>: it contains all observables stored in the platform.</li> <li>Index <code>opencti_stix_core_relationships</code>: it contains all main STIX relationships stored in the platform.</li> </ul>"},{"location":"deployment/rollover/#default-implemented-lifecycle-policy","title":"Default implemented lifecycle policy","text":"<p>Here is the recommended policy (initialized starting 5.9.X):</p> <ul> <li>Maximum primary shard size: <code>50 GB</code></li> <li>Maximum age: <code>365 days</code></li> <li>Maximum documents: <code>75,000,000</code></li> </ul>"},{"location":"deployment/rollover/#applying-rollover-policies-on-existing-indices","title":"Applying rollover policies on existing indices","text":"<p>Procedure information</p> <p>Please read the following only if your platform has been initialized before 5.9.0, otherwise lifecycle policies has been created (but you can still cutomize them).</p> <p>Unfortunately, to be able to implement rollover policies on ElasticSearch / OpenSearch indices, it will be needed to re-index all the data in new indices using ElasticSearch capabilities.</p>"},{"location":"deployment/rollover/#shutdown","title":"Shutdown","text":"<p>First step is to shutdown your OpenCTI platform.</p>"},{"location":"deployment/rollover/#change-configuration","title":"Change configuration","text":"<p>Then, in the OpenCTI configuration, change the ElasticSearch / OpenSearch default prefix to <code>octi</code> (default is <code>opencti</code>).</p>"},{"location":"deployment/rollover/#create-the-rollover-policy","title":"Create the rollover policy","text":"<p>Create a rollover policy named <code>octi-ilm-policy</code> (in Kibana, <code>Management &gt; Index Lifecycle Policies</code>):</p> <ul> <li>Maximum primary shard size: <code>50 GB</code></li> <li>Maximum age: <code>365 days</code></li> <li>Maximum documents: <code>75,000,000</code></li> </ul> <p></p>"},{"location":"deployment/rollover/#create-index-templates","title":"Create index templates","text":"<p>In Kibana, clone the <code>opencti-index-template</code> to have one index template by OpenCTI index with the appropriate rollover policy, index pattern and rollover alias (in Kibana, <code>Management &gt; Index Management &gt; Index Templates</code>).</p> <p></p> <p>Create the following index templates:</p> <ul> <li><code>octi_deleted_objects</code></li> <li><code>octi_files</code></li> <li><code>octi_history</code></li> <li><code>octi_inferred_entities</code></li> <li><code>octi_inferred_relationships</code></li> <li><code>octi_internal_objects</code></li> <li><code>octi_internal_relationships</code></li> <li><code>octi_stix_core_relationships</code></li> <li><code>octi_stix_cyber_observable_relationships</code></li> <li><code>octi_stix_cyber_observables</code></li> <li><code>octi_stix_domain_objects</code></li> <li><code>octi_stix_meta_objects</code></li> <li><code>octi_stix_meta_relationships</code></li> <li><code>octi_stix_sighting_relationships</code></li> </ul> <p>Here is the overview of all templates (you should have something with <code>octi_</code> instead of <code>opencti_</code>).</p> <p></p>"},{"location":"deployment/rollover/#apply-rollover-policy-on-all-index-templates","title":"Apply rollover policy on all index templates","text":"<p>Then, going back in the index lifecycle policies screen, you can click on the \"+\" button of the <code>octi-ilm-policy</code> to <code>Add the policy to index template</code>, then add the policy to add previously created template with the proper \"Alias for rollover index\".</p> <p></p>"},{"location":"deployment/rollover/#bootstrap-all-new-indices","title":"Bootstrap all new indices","text":"<p>Before we can re-index, we need to create the new indices with aliases.</p> <pre><code>PUT octi_history-000001\n{\n  \"aliases\": {\n    \"octi_history\": {\n      \"is_write_index\": true\n    }\n  }\n}\n</code></pre> <p>Repeat this step for all indices:</p> <ul> <li><code>octi_deleted_objects</code></li> <li><code>octi_files</code></li> <li><code>octi_history</code></li> <li><code>octi_inferred_entities</code></li> <li><code>octi_inferred_relationships</code></li> <li><code>octi_internal_objects</code></li> <li><code>octi_internal_relationships</code></li> <li><code>octi_stix_core_relationships</code></li> <li><code>octi_stix_cyber_observable_relationships</code></li> <li><code>octi_stix_cyber_observables</code></li> <li><code>octi_stix_domain_objects</code></li> <li><code>octi_stix_meta_objects</code></li> <li><code>octi_stix_meta_relationships</code></li> </ul>"},{"location":"deployment/rollover/#re-index-all-indices","title":"Re-index all indices","text":"<p>Using the <code>reindex</code> API, re-index all indices one by one:</p> <pre><code>curl -X POST \"localhost:9200/_reindex?pretty\" -H 'Content-Type: application/json' -d'\n{\n  \"source\": {\n    \"index\": \"opencti_history-000001\"\n  },\n  \"dest\": {\n    \"index\": \"octi_history\"\n  }\n}\n'\n</code></pre> <p>You will see the rollover policy to be applied and the new indices are automatically rolled-over during re-indexation.</p>"},{"location":"deployment/rollover/#delete-all-old-indices","title":"Delete all old indices","text":"<p>Then just delete all indices with the prefix <code>opencti_</code>.</p>"},{"location":"deployment/rollover/#start-your-platform","title":"Start your platform","text":"<p>Start your platform, using the new indices.</p> <p>Rollover documentation</p> <p>To have more details about automatic rollover and lifecycle policies, please read the official ElasticSearch documentation.</p>"},{"location":"deployment/troubleshooting/","title":"Troubleshooting","text":"<p>This page aims to explain the typical errors you can have with your OpenCTI platform.</p>"},{"location":"deployment/troubleshooting/#finding-the-relevant-logs","title":"Finding the relevant logs","text":"<p>It is highly recommended to monitor the error logs of the platforms, workers and connectors. All the components have log outputs in an understandable JSON format. If necessary, it is always possible to increase the log level. In production, it is recommended to have the log level set to <code>error</code>.</p>"},{"location":"deployment/troubleshooting/#platform","title":"Platform","text":"<p>Here are some useful parameters for platform logging:</p> <pre><code>- APP__APP_LOGS__LOGS_LEVEL=[error|warning|info|debug]\n- APP__APP_LOGS__LOGS_CONSOLE=true # Output in the container console\n</code></pre>"},{"location":"deployment/troubleshooting/#connectors","title":"Connectors","text":"<p>All connectors support the same set of parameters to manage the log level and outputs:</p> <pre><code>- OPENCTI_JSON_LOGGING=true # Enable / disable JSON logging\n- CONNECTOR_LOG_LEVEL=info=[error|warning|info|debug]\n</code></pre>"},{"location":"deployment/troubleshooting/#workers","title":"Workers","text":"<p>The workers can have more or less verbose outputs:</p> <pre><code>- OPENCTI_JSON_LOGGING=true # Enable / disable JSON logging\n- WORKER_LOG_LEVEL=[error|warning|info|debug]\n</code></pre>"},{"location":"deployment/troubleshooting/#elasticsearch-opensearch-data","title":"ElasticSearch / OpenSearch data","text":"<p>Kibana / OpenSearch dashboard</p> <p>In case you need to troubleshoot the OpenCTI knowledge data, we recommend to install Kibana or OpenSearch dashboard.</p>"},{"location":"deployment/troubleshooting/#common-errors","title":"Common errors","text":""},{"location":"deployment/troubleshooting/#ingestion-technical-errors","title":"Ingestion technical errors","text":"<p>Missing reference to handle creation</p> <p>After 5 retries, if an element required to create another element is missing, the platform raises an exception. It usually comes from a connector that generates inconsistent STIX 2.1 bundles.</p> <p>Cant upsert entity. Too many entities resolved</p> <p>OpenCTI received an entity which is matching too many other entities in the platform. In this condition we cannot take a decision. We need to dig into the data bundle to identify why it matches too much entities and fix the data in the bundle / or the platform according to what you expect.</p> <p>Execution timeout, too many concurrent call on the same entities</p> <p>The platform supports multi workers and multiple parallel creation but different parameters can lead to some locking timeout in the execution. </p> <ul> <li>Throughput capacity of your ElasticSearch</li> <li>Number of workers started at the same time</li> <li>Dependencies between data</li> <li>Merging capacity of OpenCTI</li> </ul> <p>If you have this kind of error, limit the number of workers deployed. Try to find the right balance of the number of workers, connectors and elasticsearch sizing.</p>"},{"location":"deployment/troubleshooting/#ingestion-functional-errors","title":"Ingestion functional errors","text":"<p>Indicator of type yara is not correctly formatted</p> <p>OpenCTI check the validity of the indicator rule.</p> <p>Observable of type IPv4-Addr is not correctly formatted</p> <p>OpenCTI check the validity of the observable value.</p>"},{"location":"deployment/troubleshooting/#dependencies-errors","title":"Dependencies errors","text":"<p>TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark...</p> <p>Disk full, no space left on the device for ElasticSearch.</p>"},{"location":"deployment/upgrade/","title":"Upgrade","text":"<p>Depending on your installation mode, upgrade path may change.</p> <p>Migrations</p> <p>The platform is taking care of all necessary underlying migrations in the databases if any. You can upgrade OpenCTI from any version to the latest one, including skipping multiple major releases.</p>"},{"location":"deployment/upgrade/#using-docker","title":"Using Docker","text":"<p>Before applying this procedure, please update your <code>docker-compose.yml</code> file with the new version number of container images.</p>"},{"location":"deployment/upgrade/#for-single-node-docker","title":"For single node Docker","text":"<pre><code>$ sudo docker-compose stop\n$ sudo docker-compose pull\n$ sudo docker-compose up -d\n</code></pre>"},{"location":"deployment/upgrade/#for-docker-swarm","title":"For Docker swarm","text":"<p>For each of services, you have to run the following command:</p> <pre><code>$ sudo docker service update --force service_name\n</code></pre>"},{"location":"deployment/upgrade/#manual-installation","title":"Manual installation","text":"<p>When upgrading the platform, you have to replace all files and restart the platform, the database migrations will be done automatically:</p> <pre><code>$ yarn serv\n</code></pre>"},{"location":"development/api-usage/","title":"GraphQL playground","text":"<p>The GraphQL playground is an integrated development environment (IDE) provided by OpenCTI for exploring and testing GraphQL APIs. It offers a user-friendly interface that allows developers to interactively query the GraphQL schema, experiment with different queries, and visualize the responses.</p>"},{"location":"development/api-usage/#key-features","title":"Key features","text":""},{"location":"development/api-usage/#interactive-querying","title":"Interactive querying","text":"<p>The Playground provides a text editor where developers can write GraphQL queries, mutations, and subscriptions. As you type, the Playground offers syntax highlighting, autocompletion, and error checking to aid in query composition.</p> <p></p>"},{"location":"development/api-usage/#documentation","title":"Documentation","text":"<p>Developers can access comprehensive documentation for the GraphQL schema directly within the Playground. This documentation includes descriptions of all available types, fields, and directives, making it easy to understand the data model and construct queries.</p> <p></p>"},{"location":"development/api-usage/#query-history","title":"Query history","text":"<p>The playground keeps track of previously executed queries, allowing developers to revisit and reuse queries from previous sessions. This feature streamlines the development process by eliminating the need to retype complex queries.</p> <p></p>"},{"location":"development/api-usage/#response-visualization","title":"Response visualization","text":"<p>Upon executing a query, the playground displays the response data in a structured and readable format. JSON responses are presented in a collapsible tree view, making it easy to navigate nested data structures and inspect individual fields.</p> <p></p>"},{"location":"development/api-usage/#schema-exploration","title":"Schema exploration","text":"<p>Developers can explore the GraphQL schema using the built-in schema viewer. This feature provides a graphical representation of the schema, showing types, fields, and their relationships. Developers can explore the schema and understand its structure.</p> <p></p>"},{"location":"development/api-usage/#getting-started","title":"Getting started","text":"<p>To access the GraphQL playground, navigate to the GraphQL endpoint of your OpenCTI instance: <code>https://[your-opencti-instance]/graphql</code>. Then, follow these steps to utilize the playground:</p> <ol> <li>Query editor: Write GraphQL queries, mutations, and subscriptions in the text editor. Use syntax highlighting and autocompletion to speed up query composition.</li> <li>Documentation explorer: Access documentation for the GraphQL schema by clicking on the \"Docs\" tab on the right. Browse types, fields, and descriptions to understand the available data and query syntax.</li> <li>Query history: View and execute previously executed queries from the \"History\" tab on the top. Reuse queries and experiment with variations without retyping.</li> <li>Response pane: Visualize query responses in the response pane. Expand and collapse sections to navigate complex data structures and inspect individual fields.</li> <li>Schema viewer: Explore the GraphQL schema interactively using the \"Schema\" tab on the right. Navigate types, fields, and relationships to understand the data model and plan queries.</li> </ol>"},{"location":"development/api-usage/#external-resources","title":"External Resources","text":"<p>For a more in-depth understanding of GraphQL and its usage, consider exploring the following external resources:</p> <ul> <li>GraphQL Official Documentation</li> <li>GraphQL query documentation</li> <li>How to GraphQL</li> </ul>"},{"location":"development/connectors/","title":"Connector development","text":""},{"location":"development/connectors/#introduction","title":"Introduction","text":"<p>A connector in OpenCTI is a service that runs next to the platform and can be implemented in almost any programming language that has STIX2 support. Connectors are used to extend the functionality of OpenCTI and allow operators to shift some of the processing workload to external services. To use the conveniently provided OpenCTI connector SDK you need to use Python3 at the moment.</p> <p>We choose to have a very decentralized approach on connectors, in order to bring a maximum freedom to developers and vendors. So a connector on OpenCTI can be defined by a standalone Python 3 process that pushes an understandable format of data to an ingestion queue of messages.</p> <p>Each connector must implement a long-running process that can be launched just by executing the main Python file. The only mandatory dependency is the <code>OpenCTIConnectorHelper</code> class that enables the connector to send data to OpenCTI.</p>"},{"location":"development/connectors/#getting-started","title":"Getting started","text":"<p>In the beginning first think about your use-case to choose and appropriate connector type - what do want to achieve with your connector? The following table gives you an overview of the current connector types and some typical use-cases:</p> <p>Connector types</p> Type Typical use cases Example connector EXTERNAL_IMPORT Integrate external TI provider, Integrate external TI platform AlienVault INTERNAL_ENRICHMENT Enhance existing data with additional knowledge AbuseIP INTERNAL_IMPORT_FILE (Bulk) import knowledge from files Import document INTERNAL_EXPORT_FILE (Bulk) export knowledge to files STIX 2.1, CSV. STREAM Integrate external TI provider, Integrate external TI platform Elastic Security <p>After you've selected your connector type make yourself familiar with STIX2 and the supported relationships in OpenCTI. Having some knowledge about the internal data models with help you a lot with the implementation of your idea.</p>"},{"location":"development/connectors/#preparation","title":"Preparation","text":""},{"location":"development/connectors/#environment-setup","title":"Environment Setup","text":"<p>To develop and test your connector, you need a running OpenCTI instance with the frontend and the messaging broker accessible. If you don't plan on developing anything for the OpenCTI platform or the frontend, the easiest setup for the connector development is using the docker setup, For more details see here.</p>"},{"location":"development/connectors/#coding-setup","title":"Coding Setup","text":"<p>To give you an easy starting point we prepared an example connector in the public repository you can use as template to bootstrap your development.</p> <p>Some prerequisites we recommend to follow this tutorial:</p> <ul> <li>Code editor with good Python3 support (e.g. Visual Studio Code with the Python extension pack)</li> <li>Python3 + setuptools is installed and configured</li> <li>Command shell (either Linux/Mac terminal or WSL on Windows)</li> </ul> <p>In the terminal check out the connectors repository and copy the template connector to <code>$myconnector</code> (replace it with your name throughout the following text examples).</p> <pre><code>$ pip3 install black flake8 pycti\n# Fork the current repository, then clone your fork\n$ git clone https://github.com/YOUR-USERNAME/connectors.git\n$ cd connectors\n$ git remote add upstream https://github.com/OpenCTI-Platform/connectors.git\n# Create a branch for your feature/fix\n$ git checkout -b [branch-name]\n# Copy the appropriate template directory for the connector type\n$ cp -r templates/$connector_type $connector_type/$myconnector\n$ cd $connector_type/$myconnector\n$ ls -R\nDockerfile              docker-compose.yml      requirements.txt\nREADME.md               entrypoint.sh           src\n\n./src:\nlib     main.py\n\n./src/lib:\n$connector_type.py\n</code></pre>"},{"location":"development/connectors/#changing-the-template","title":"Changing the template","text":"<p>There are a few files in the template we need to change for our connector to be unique. You can check for all places you need to change you connector name with the following command (the output will look similar):</p> <pre><code>$ grep -Ri template .\n\nREADME.md:# OpenCTI Template Connector\nREADME.md:| `connector_type`                     | `CONNECTOR_TYPE`                    | Yes          | Must be `Template_Type` (this is the connector type).                                                                                                      |\nREADME.md:| `connector_name`                     | `CONNECTOR_NAME`                    | Yes          | Option `Template`                                                                                                                                          |\nREADME.md:| `connector_scope`                    | `CONNECTOR_SCOPE`                   | Yes          | Supported scope: Template Scope (MIME Type or Stix Object)                                                                                                 |\nREADME.md:| `template_attribute`                 | `TEMPLATE_ATTRIBUTE`                | Yes          | Additional setting for the connector itself                                                                                                                |\ndocker-compose.yml:  connector-template:\ndocker-compose.yml:    image: opencti/connector-template:4.5.5\ndocker-compose.yml:      - CONNECTOR_TYPE=Template_Type\ndocker-compose.yml:      - CONNECTOR_NAME=Template\ndocker-compose.yml:      - CONNECTOR_SCOPE=Template_Scope # MIME type or Stix Object\nentrypoint.sh:cd /opt/opencti-connector-template\nDockerfile:COPY src /opt/opencti-template\nDockerfile:    cd /opt/opencti-connector-template &amp;&amp; \\\nsrc/main.py:class Template:\nsrc/main.py:            \"TEMPLATE_ATTRIBUTE\", [\"template\", \"attribute\"], config, True\nsrc/main.py:        connectorTemplate = Template()\nsrc/main.py:        connectorTemplate.run()\nsrc/config.yml.sample:  type: 'Template_Type'\nsrc/config.yml.sample:  name: 'Template'\nsrc/config.yml.sample:  scope: 'Template_Scope' # MIME type or SCO\n</code></pre> <p>Required changes:</p> <ul> <li> Change <code>Template</code> or <code>template</code>mentions to your connector name e.g. <code>ImportCsv</code> or <code>importcsv</code></li> <li> Change <code>TEMPLATE</code> mentions to your connector name e.g. <code>IMPORTCSV</code></li> <li> Change <code>Template_Scope</code> mentions to the required scope of your connector. For processing imported files, that can be the Mime type e.g. <code>application/pdf</code> or for enriching existing information in OpenCTI, define the STIX object's name e.g. <code>Report</code>. Multiple scopes can be separated by a simple <code>,</code></li> <li> Change <code>Template_Type</code> to the connector type you wish to develop. The OpenCTI types are defined hereafter:<ul> <li>EXTERNAL_IMPORT</li> <li>INTERNAL_ENRICHMENT</li> <li>INTERNAL_EXPORT_FILE</li> <li>INTERNAL_IMPORT_FILE </li> <li>STREAM</li> </ul> </li> </ul>"},{"location":"development/connectors/#development","title":"Development","text":""},{"location":"development/connectors/#initialize-the-opencti-connector-helper","title":"Initialize the OpenCTI connector helper","text":"<p>After getting the configuration parameters of your connector, you have to initialize the OpenCTI connector helper by using the <code>pycti</code> Python library. This is shown in the following example:</p> <pre><code>class TemplateConnector:\n    def __init__(self):\n                # Instantiate the connector helper from config\n        config_file_path = os.path.dirname(os.path.abspath(__file__)) + \"/config.yml\"\n        config = (\n            yaml.load(open(config_file_path), Loader=yaml.SafeLoader)\n            if os.path.isfile(config_file_path)\n            else {}\n        )\n        self.helper = OpenCTIConnectorHelper(config)\n                self.custom_attribute = get_config_variable(\n            \"TEMPLATE_ATTRIBUTE\", [\"template\", \"attribute\"], config\n        )\n</code></pre> <p>Since there are some basic differences in the tasks of the different connector classes, the structure is also a bit class dependent. While the external-import and the stream connector run independently in a regular interval or constantly, the other 3 connector classes only run when being requested by the OpenCTI platform.</p> <p>The self-triggered connectors run independently, but the OpenCTI need to define a callback function, which can be executed for the connector to start its work. This is done via         <code>self.helper.listen(self._process_message)</code> . In the appended examples, the difference of the setup can be seen.</p> <p>Self-triggered Connectors</p> <ul> <li>external-import</li> <li>stream</li> </ul> <p>OpenCTI triggered</p> <ul> <li>internal-enrichment</li> <li>internal-import</li> <li>internal-export</li> </ul> <pre><code>from pycti import OpenCTIConnectorHelper, get_config_variable\n\nclass TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n        self.template_interval = get_config_variable(\n            \"TEMPLATE_INTERVAL\", [\"template\", \"interval\"], config, True\n        )\n\n    def get_interval(self) -&gt; int:\n        return int(self.template_interval) * 60 * 60 * 24\n\n    def run(self) -&gt; None:\n                # Main procedure\n\nif __name__ == \"__main__\":\n    try:\n        template_connector = TemplateConnector()\n        template_connector.run()\n    except Exception as e:\n        print(e)\n        time.sleep(10)\n        exit(0)\n</code></pre> <pre><code>from pycti import OpenCTIConnectorHelper, get_config_variable\n\nclass TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n\n    def _process_message(self, data: dict) -&gt; str:\n                # Main procedure                \n\n    # Start the main loop\n    def start(self) -&gt; None:\n        self.helper.listen(self._process_message)\n\nif __name__ == \"__main__\":\n    try:\n        template_connector = TemplateConnector()\n        template_connector.start()\n    except Exception as e:\n        print(e)\n        time.sleep(10)\n        exit(0)\n</code></pre>"},{"location":"development/connectors/#write-and-read-operations","title":"Write and Read Operations","text":"<p>When using the <code>OpenCTIConnectorHelper</code> class, there are two way for reading from or writing data to the OpenCTI platform.</p> <ol> <li>via the OpenCTI API interface via <code>self.helper.api</code></li> <li>via the OpenCTI worker via <code>self.send_stix2_bundle</code></li> </ol>"},{"location":"development/connectors/#sending-data-to-the-opencti-platform","title":"Sending data to the OpenCTI platform","text":"<p>The recommended way for creating or updating data in the OpenCTI platform is via the OpenCTI worker. This enables the connector to just send and forget about thousands of entities at once to without having to think about the ingestion order, performance or error handling.</p>  \u26a0\ufe0f **Please DO NOT use the api interface to create new objects in connectors.**   <p>The OpenCTI connector helper method <code>send_stix2_bundle</code> must be used to send data to OpenCTI. The <code>send_stix2_bundle</code> function takes 2 arguments.</p> <ol> <li>A serialized STIX2 bundle as a <code>string</code> (mandatory)</li> <li>A <code>list</code> of entities types that should be ingested (optional)</li> </ol> <p>Here is an example using the STIX2 Python library:</p> <pre><code>from stix2 import Bundle, AttackPattern\n\n[...]\n\nattack_pattern = AttackPattern(name='Evil Pattern')\n\nbundle_objects = []\nbundle_objects.append(attack_pattern)\n\nbundle = Bundle(objects=bundle_objects).serialize()\nbundles_sent = self.opencti_connector_helper.send_stix2_bundle(bundle)\n</code></pre>"},{"location":"development/connectors/#reading-from-the-opencti-platform","title":"Reading from the OpenCTI platform","text":"<p>Read queries to the OpenCTI platform can be achieved using the API and the STIX IDs can be attached to reports to create the relationship between those two entities.</p> <pre><code>entity = self.helper.api.vulnerability.read(\n    filters={\"key\": \"name\", \"values\": [\"T1234\"]}\n)\n</code></pre> <p>If you want to add the found entity via <code>objects_refs</code> to another SDO, simple add a list of <code>stix_ids</code> to the SDO. Here's an example using the entity from the code snippet above:</p> <pre><code>from stix2 import Report\n\n[...]\n\nreport = Report(\n    id=report[\"standard_id\"],\n  object_refs=[entity[\"standard_id\"]],\n)\n</code></pre>"},{"location":"development/connectors/#logging","title":"Logging","text":"<p>When something crashes at a user's, you as a developer want to know as much as possible about this incident to easily improve your code and remove this issue. To do so, it is very helpful if your connector documents what it does. Use <code>info</code> messages for big changes like the beginning or the finishing of an operation, but to facilitate your bug removal attempts, implement <code>debug</code> messages for minor operation changes to document different steps in your code.</p> <p>When encountering a crash, the connector's user can easily restart the troubling connector with the debug logging activated.</p> <ul> <li><code>CONNECTOR_LOG_LEVEL=debug</code></li> </ul> <p>Using those additional log messages, the bug report is more enriched with information about the possible cause of the problem. Here's an example of how the logging should be implemented:</p> <pre><code>        def run(self) -&gt; None:\n                self.helper.log_info('Template connector starts')\n                results = self._ask_for_news()\n                [...]\n\n        def _ask_for_news() -&gt; None:\n                overall = []\n                for i in range(0, 10):\n                        self.log_debug(f\"Asking about news with count '{i}'\")\n                        # Do something\n                        self.log_debug(f\"Resut: '{result}'\")\n                        overall.append(result)\n                return overall\n</code></pre> <p>Please make sure that the debug messages rich of useful information, but that they are not redundant and that the user is not drowned by unnecessary information.</p>"},{"location":"development/connectors/#additional-implementations","title":"Additional implementations","text":"<p>If you are still unsure about how to implement certain things in your connector, we advise you to have a look at the code of other connectors of the same type. Maybe they are already using approach which is suitable for addressing to your problem.</p>"},{"location":"development/connectors/#opencti-triggered-connector-special-cases","title":"OpenCTI triggered Connector - Special cases","text":""},{"location":"development/connectors/#data-layout-of-dictionary-from-callback-function","title":"Data Layout of Dictionary from Callback function","text":"<p>OpenCTI sends the connector a few instructions via the <code>data</code> dictionary in the callback function. Depending on the connector type, the data dictionary content is a bit different. Here are a few examples for each connector type.</p> <p>Internal Import Connector</p> <p>Internal Enrichment Connector</p> <pre><code>{ \n  \"file_id\": \"&lt;fileId&gt;\",\n  \"file_mime\": \"application/pdf\", \n  \"file_fetch\": \"storage/get/&lt;file_id&gt;\", // Path to get the file\n  \"entity_id\": \"report--82843863-6301-59da-b783-fe98249b464e\", // Context of the upload\n}\n</code></pre> <pre><code>{ \n  \"entity_id\": \"&lt;stixCoreObjectId&gt;\" // StixID of the object wanting to be enriched\n}\n</code></pre> <p>Internal Export Connector</p> <pre><code>{ \n  \"export_scope\": \"single\", // 'single' or 'list'\n  \"export_type\": \"simple\", // 'simple' or 'full'\n  \"file_name\": \"&lt;fileName&gt;\", // Export expected file name\n  \"max_marking\": \"&lt;maxMarkingId&gt;\", // Max marking id\n  \"entity_type\": \"AttackPattern\", // Exported entity type\n  // ONLY for single entity export\n  \"entity_id\": \"&lt;entity.id&gt;\", // Exported element\n  // ONLY for list entity export\n  \"list_params\": \"[&lt;parameters&gt;]\" // Parameters for finding entities\n}\n</code></pre>"},{"location":"development/connectors/#self-triggered-connector-special-cases","title":"Self triggered Connector - Special cases","text":""},{"location":"development/connectors/#initiating-a-work-before-pushing-data","title":"Initiating a 'Work' before pushing data","text":"<p>For self-triggered connectors, OpenCTI has to be told about new jobs to process and to import. This is done by registering a so called <code>work</code> before sending the stix bundle and signalling the end of a work. Here an example:</p> <p>By implementing the work registration, they will show up as shown in this screenshot for the MITRE ATT&amp;CK connector:</p> <pre><code>def run() -&gt; None:\n        # Anounce upcoming work\n        timestamp = int(time.time())\n        now = datetime.utcfromtimestamp(timestamp)\n    friendly_name = \"Template run @ \" + now.strftime(\"%Y-%m-%d %H:%M:%S\")\n    work_id = self.helper.api.work.initiate_work(\n                self.helper.connect_id, friendly_name\n        )\n\n        [...]\n        # Send Stix bundle\n        self.helper.send_stix2_bundle(\n                bundle,\n                entities_types=self.helper.connect_scope,\n                update=True,\n                work_id=work_id,\n        )\n        # Finish the work\n        self.helper.log_info(\n            f\"Connector successfully run, storing last_run as {str(timestamp)}\"\n    )              \n        message = \"Last_run stored, next run in: {str(round(self.get_interval() / 60 / 60 / 24, 2))} days\"\n        self.helper.api.work.to_processed(work_id, message)\n</code></pre>"},{"location":"development/connectors/#interval-handling","title":"Interval handling","text":"<p>The connector is also responsible for making sure that it runs in certain intervals. In most cases, the intervals are definable in the connector config and then only need to be set and updated during the runtime.</p> <pre><code>class TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n        self.template_interval = get_config_variable(\n            \"TEMPLATE_INTERVAL\", [\"template\", \"interval\"], config, True\n        )\n\n    def get_interval(self) -&gt; int:\n        return int(self.template_interval) * 60 * 60 * 24\n\n        def run(self) -&gt; None:\n        self.helper.log_info(\"Fetching knowledge...\")\n        while True:\n            try:\n                # Get the current timestamp and check\n                timestamp = int(time.time())\n                current_state = self.helper.get_state()\n                if current_state is not None and \"last_run\" in current_state:\n                    last_run = current_state[\"last_run\"]\n                    self.helper.log_info(\n                        \"Connector last run: \"\n                        + datetime.utcfromtimestamp(last_run).strftime(\n                            \"%Y-%m-%d %H:%M:%S\"\n                        )\n                    )\n                else:\n                    last_run = None\n                    self.helper.log_info(\"Connector has never run\")\n                # If the last_run is more than interval-1 day\n                if last_run is None or (\n                    (timestamp - last_run)\n                    &gt; ((int(self.template_interval) - 1) * 60 * 60 * 24)\n                ):\n                    timestamp = int(time.time())\n                    now = datetime.utcfromtimestamp(timestamp)\n                    friendly_name = \"Connector run @ \" + now.strftime(\"%Y-%m-%d %H:%M:%S\")\n\n                                        ###\n                                        # RUN CODE HERE     \n                                        ###\n\n                    # Store the current timestamp as a last run\n                    self.helper.log_info(\n                        \"Connector successfully run, storing last_run as \"\n                        + str(timestamp)\n                    )\n                    self.helper.set_state({\"last_run\": timestamp})\n                    message = (\n                        \"Last_run stored, next run in: \"\n                        + str(round(self.get_interval() / 60 / 60 / 24, 2))\n                        + \" days\"\n                    )\n                    self.helper.api.work.to_processed(work_id, message)\n                    self.helper.log_info(message)\n                    time.sleep(60)\n                else:\n                    new_interval = self.get_interval() - (timestamp - last_run)\n                    self.helper.log_info(\n                        \"Connector will not run, next run in: \"\n                        + str(round(new_interval / 60 / 60 / 24, 2))\n                        + \" days\"\n                    )\n                    time.sleep(60)\n</code></pre>"},{"location":"development/connectors/#running-the-connector","title":"Running the connector","text":"<p>For development purposes, it is easier to simply run the python script locally until everything works as it sould.</p> <pre><code>$ virtualenv env\n$ source ./env/bin/activate\n$ pip3 install -r requirements\n$ cp config.yml.sample config.yml\n# Define the opencti url and token, as well as the connector's id\n$ vim config.yml\n$ python3 main.py\nINFO:root:Listing Threat-Actors with filters null.\nINFO:root:Connector registered with ID: a2de809c-fbb9-491d-90c0-96c7d1766000\nINFO:root:Starting ping alive thread\n...\n</code></pre>"},{"location":"development/connectors/#final-testing","title":"Final Testing","text":"<p>Before submitting a Pull Request, please test your code for different use cases and scenarios. We don't have an automatic testing suite for the connectors yet, thus we highly depend on developers thinking about creative scenarios their code could encounter.</p>"},{"location":"development/connectors/#prepare-for-release","title":"Prepare for release","text":"<p>If you plan to provide your connector to be used by the community (\u2764\ufe0f) your code should pass the following (minimum) criteria.</p> <pre><code># Linting with flake8 contains no errors or warnings\n$ flake8 --ignore=E,W\n# Verify formatting with black\n$ black .\nAll done! \u2728 \ud83c\udf70 \u2728\n1 file left unchanged.\n# Verify import sorting\n$ isort --profile black .\nFixing /path/to/connector/file.py\n# Push you feature/fix on Github\n$ git add [file(s)]\n$ git commit -m \"[connector_name] descriptive message\"\n$ git push origin [branch-name]\n# Open a pull request with the title \"[connector_name] message\"\n</code></pre> <p>If you have any trouble with this just reach out to the OpenCTI core team. We are happy to assist with this.</p>"},{"location":"development/environment_ubuntu/","title":"Prerequisites Ubuntu","text":"<p>Development stack require some base software that need to be installed.</p>"},{"location":"development/environment_ubuntu/#docker-or-podman","title":"Docker or podman","text":"<p>Platform dependencies in development are deployed through container management, so you need to install a container stack.</p> <p>We currently support docker and podman.</p> <pre><code>$ sudo apt-get install docker docker-compose curl\n</code></pre> <pre><code>sudo apt-get -y install podman\n</code></pre> <p>As OpenCTI has a dependency to ElasticSearch, you have to set the vm.max_map_count before running the containers, as mentioned in the ElasticSearch documentation.</p> <pre><code>$ sudo sysctl -w vm.max_map_count=262144\n</code></pre>"},{"location":"development/environment_ubuntu/#nodejs-and-yarn","title":"NodeJS and yarn","text":"<p>The platform is developed on nodejs technology, so you need to install node and the yarn package manager.</p> <pre><code>$ sudo apt-get install nodejs\n$ sudo curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -\n$ sudo echo \"deb https://dl.yarnpkg.com/debian/ stable main\" | sudo tee /etc/apt/sources.list.d/yarn.list\n$ sudo apt-get update &amp;&amp; sudo apt-get install yarn\n</code></pre>"},{"location":"development/environment_ubuntu/#python-runtime","title":"Python runtime","text":"<p>For worker and connectors, a python runtime is needed.</p> <pre><code>$ sudo apt-get install python3 python3-pip\n</code></pre>"},{"location":"development/environment_ubuntu/#git-and-dev-tool","title":"Git and dev tool","text":"<ul> <li>Install Git from apt</li> </ul> <pre><code>$ sudo apt-get install git-all\n</code></pre> <ul> <li>Install your preferred IDE<ul> <li>Intellij community edition - https://www.jetbrains.com/idea/download/</li> <li>VSCode - https://code.visualstudio.com/</li> </ul> </li> </ul>"},{"location":"development/environment_windows/","title":"Prerequisites Windows","text":"<p>Development stack require some base software that need to be installed.</p>"},{"location":"development/environment_windows/#docker-or-podman","title":"Docker or podman","text":"<p>Platform dependencies in development are deployed through container management, so you need to install a container stack.</p> <p>We currently support docker and postman.</p> <p>Docker Desktop from - https://docs.docker.com/desktop/install/windows-install/</p> <ul> <li>Install new version of - https://docs.microsoft.com/windows/wsl/wsl2-kernel. This will require a reboot.</li> <li>Shell out to CMD as Administrator and run the following powershell command: </li> </ul> <p><code>wsl --set-default-version 2</code></p> <ul> <li>Reboot computer and continue to next step       </li> <li>Load Docker Application</li> <li>NOTE DOCKER LICENSE - You are agreeing to the licence for Non-commercial Open Source Project use. OpenCTI is Open Source and the version you would be possibly contributing to enhancing is the unpaid non-commercial/non-enterprise version. If you intention is different - please consult with your organization's legal/licensing department.</li> <li>Leave Docker Desktop running</li> </ul>"},{"location":"development/environment_windows/#nodejs-and-yarn","title":"NodeJS and yarn","text":"<p>The platform is developed on nodejs technology, so you need to install node and the yarn package manager.</p> <ul> <li>Install NodeJS from - https://nodejs.org/download/release/v16.20.0/node-v16.20.0-x64.msi</li> <li>Select the option for installing Chocolatey on the Tools for Native Modules screen<ul> <li>Will do this install for you automatically - https://chocolatey.org/packages/visualstudio2019-workload-vctools</li> <li>Includes Python 3.11.4</li> </ul> </li> <li> <p>Shell out to CMD prompt as Administrator and install/run:</p> <ul> <li><code>pip3 install pywin32</code></li> </ul> </li> <li> <p>Configure Yarn (https://yarnpkg.com/getting-started/install)</p> </li> <li>Open CMD as Administrator and run the following command:<ul> <li><code>corepack enable</code></li> </ul> </li> </ul>"},{"location":"development/environment_windows/#python-runtime","title":"Python runtime","text":"<p>For worker and connectors, a python runtime is needed. Even if you already have a python runtime installed through node installation,  on windows some nodejs package will be recompiled with python and C++ runtime. </p> <p>For this reason Visual Studio Build Tools is required.</p> <ul> <li>Install Visual Studio Build Tools from - https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools</li> <li>Check off Desktop Development with C++</li> <li>Run install</li> </ul>"},{"location":"development/environment_windows/#git-and-dev-tool","title":"Git and dev tool","text":"<ul> <li>Download GIT for Windows (64-bit Setup)- https://git-scm.com/download/win</li> <li> <p>Just use defaults on each screen</p> </li> <li> <p>Install your preferred IDE</p> </li> <li>Intellij community edition - https://www.jetbrains.com/idea/download/</li> <li>VSCode - https://code.visualstudio.com/docs/?dv=win64</li> </ul>"},{"location":"development/platform/","title":"Platform development","text":""},{"location":"development/platform/#introduction","title":"Introduction","text":"<p>This summary should give you a detailed setup description for initiating the OpenCTI setup environment  necessary for developing on the OpenCTI platform, a client library or the connectors.  This page document how to set up an \"All-in-One\" development environment for OpenCTI.  The devenv will contain data of 3 different repositories:</p> <ul> <li>Platform: https://github.com/OpenCTI-Platform/opencti</li> <li>Connectors: https://github.com/OpenCTI-Platform/connectors</li> <li>Client python: https://github.com/OpenCTI-Platform/client-python</li> </ul>"},{"location":"development/platform/#platform","title":"Platform","text":"<p>Contains the platform OpenCTI project code base:</p> <ul> <li>docker-compose (docker or podman) <code>~/opencti/opencti-platform/opencti-dev</code></li> <li>Web frontend (nodejs / react) <code>~/opencti/opencti-platform/opencti-graphql</code></li> <li>Backend (nodejs) <code>~/opencti/opencti-platform/opencti-frontend</code></li> <li>Worker (nodejs / python) <code>~/opencti/opencti-worker</code></li> </ul>"},{"location":"development/platform/#connectors","title":"Connectors","text":"<p>Contains a lot of developed connectors, as a source of inspiration for your new connector.</p>"},{"location":"development/platform/#client-python","title":"Client python","text":"<p>Contains the source code of the python library used in worker or connectors.</p>"},{"location":"development/platform/#prerequisites","title":"Prerequisites","text":"<p>Some tools are needed before starting to develop. Please check Ubuntu prerequisites or Windows prerequisites</p>"},{"location":"development/platform/#clone-the-projects","title":"Clone the projects","text":"<p>Fork and clone the git repositories</p> <ul> <li>https://github.com/OpenCTI-Platform/opencti/ - frontend / backend</li> <li>https://github.com/OpenCTI-Platform/connectors - connectors</li> <li>https://github.com/OpenCTI-Platform/docker - docker stack</li> <li>https://github.com/OpenCTI-Platform/client-python/ - python client</li> </ul>"},{"location":"development/platform/#dependencies-containers","title":"Dependencies containers","text":"<p>In development dependencies are deployed trough containers. A development compose file is available in <code>~/opencti/opencti-platform/opencti-dev</code></p> <pre><code>cd ~/docker\n#Start the stack in background\ndocker-compose -f ./docker-compose-dev.yml up -d\n</code></pre> <p>You have now all the dependencies of OpenCTI running and waiting for product to run.</p>"},{"location":"development/platform/#backend-api","title":"Backend / API","text":""},{"location":"development/platform/#python-virtual-env","title":"Python virtual env","text":"<p>The GraphQL API is developed in JS and with some python code.  As it's an \"all-in-one\" installation, the python environment will be installed in a virtual environment.</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\npython3 -m venv .venv --prompt \"graphql\"\nsource .venv/bin/activate\npip install --upgrade pip wheel setuptools\nyarn install\nyarn install:python \ndeactivate\n</code></pre>"},{"location":"development/platform/#development-configuration","title":"Development configuration","text":"<p>The API can be specifically configured with files depending on the starting profile. By default, the default.json file is used and will be correctly configured for local usage except for admin password</p> <p>So you need to create a development profile file. You can duplicate the default file and adapt if for you need. <pre><code>cd ~/opencti/opencti-platform/opencti-graphql/config\ncp default.json development.json\n</code></pre></p> <p>At minimum adapt the admin part for the password and token. <pre><code>    \"admin\": {\n      \"email\": \"admin@opencti.io\",\n      \"password\": \"MyNewPassord\",\n      \"token\": \"UUID generated with https://www.uuidgenerator.net\"\n    }\n</code></pre></p>"},{"location":"development/platform/#install-start","title":"Install / start","text":"<p>Before starting the backend you need to install the nodejs modules</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\nyarn install\n</code></pre> <p>Then you can simply start the backend API with the yarn start command</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\nyarn start\n</code></pre> <p>The platform will start logging some interesting information</p> <pre><code>{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] Starting platform\",\"timestamp\":\"2023-07-02T16:37:10.984Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] Checking dependencies statuses\",\"timestamp\":\"2023-07-02T16:37:10.987Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[SEARCH] Elasticsearch (8.5.2) client selected / runtime sorting enabled\",\"timestamp\":\"2023-07-02T16:37:11.014Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[CHECK] Search engine is alive\",\"timestamp\":\"2023-07-02T16:37:11.015Z\",\"version\":\"5.8.7\"}\n...\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[INIT] Platform initialization done\",\"timestamp\":\"2023-07-02T16:37:11.622Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] API ready on port 4000\",\"timestamp\":\"2023-07-02T16:37:12.382Z\",\"version\":\"5.8.7\"}\n</code></pre> <p>If you want to start on another profile you can use the -e parameter. For example here to use the profile.json configuration file.</p> <pre><code>yarn start -e profile\n</code></pre>"},{"location":"development/platform/#code-check","title":"Code check","text":"<p>Before pushing your code you need to validate the syntax and ensure the testing will be validated.</p>"},{"location":"development/platform/#for-validation","title":"For validation","text":"<p><code>yarn lint</code></p> <p><code>yarn check-ts</code></p>"},{"location":"development/platform/#for-testing","title":"For testing","text":"<p>For starting the test you will need to create a test.json configuration file. You can use the same dependencies by only adapting all prefix for all dependencies.</p> <p>Tests are using dedicated indices in the Elastic database (prefixed with <code>test-*</code> or the prefix that you have set up in test.json).</p> <p>The following command will run the complete test suite using vitest, which might take more than 30 minutes. It starts by cleaning up the test database and seeding a minimal dataset. The file <code>vitest.config.test.ts</code> can be edited to run only a specific file pattern.</p> <p><code>yarn test:dev</code></p> <p>We also provide utility scripts to ease the development of new tests, especially integration tests that rely on the sample data  loaded after executing <code>00-inject/loader-test.ts</code>.</p> <p>To solely initialize the test database with this sample dataset run:</p> <p><code>yarn test:dev:init</code></p> <p>And then, execute the following command to run the pattern specified in the file <code>vitest.config.test.ts</code>, or add a file name to the command line to run only this test file.</p> <p><code>yarn test:dev:resume</code></p> <p>This last command will NOT cleanup &amp; initialize the test database and thus will be quicker to execute. </p>"},{"location":"development/platform/#frontend","title":"Frontend","text":""},{"location":"development/platform/#install-start_1","title":"Install / start","text":"<p>Before starting the backend you need to install the nodejs modules</p> <pre><code>cd ~/opencti/opencti-platform/opencti-front\nyarn install\n</code></pre> <p>Then you can simply start the frontend with the yarn start command</p> <pre><code>cd ~/opencti/opencti-platform/opencti-front\nyarn start\n</code></pre> <p>The frontend will start with some interesting information</p> <pre><code>[INFO] [default] compiling...\n[INFO] [default] compiled documents: 1592 reader, 1072 normalization, 1596 operation text\n[INFO] Compilation completed.\n[INFO] Done.\n[HPM] Proxy created: /stream  -&gt; http://localhost:4000\n[HPM] Proxy created: /storage  -&gt; http://localhost:4000\n[HPM] Proxy created: /taxii2  -&gt; http://localhost:4000\n[HPM] Proxy created: /feeds  -&gt; http://localhost:4000\n[HPM] Proxy created: /graphql  -&gt; http://localhost:4000\n[HPM] Proxy created: /auth/**  -&gt; http://localhost:4000\n[HPM] Proxy created: /static/flags/**  -&gt; http://localhost:4000\n</code></pre> <p>The web UI should be accessible on http://127.0.0.1:3000</p>"},{"location":"development/platform/#code-check_1","title":"Code check","text":"<p>Before pushing your code you need to validate the syntax and ensure the testing will be validated.</p>"},{"location":"development/platform/#for-validation_1","title":"For validation","text":"<p><code>yarn lint</code></p> <p><code>yarn check-ts</code></p>"},{"location":"development/platform/#for-testing_1","title":"For testing","text":"<p><code>yarn test</code></p>"},{"location":"development/platform/#worker","title":"Worker","text":"<p>Running a worker is required when you want to develop on the ingestion or import/export connectors.</p>"},{"location":"development/platform/#python-virtual-env_1","title":"Python virtual env","text":"<pre><code>cd ~/opencti/opencti-worker/src\npython3 -m venv .venv --prompt \"worker\"\nsource .venv/bin/activate\npip3 install --upgrade pip wheel setuptools\npip3 install -r requirements.txt\ndeactivate\n</code></pre>"},{"location":"development/platform/#install-start_2","title":"Install / start","text":"<pre><code>cd ~/opencti/opencti-worker/src\nsource .venv/bin/activate\npython worker.py\n</code></pre>"},{"location":"development/platform/#connectors_1","title":"Connectors","text":"<p>For connectors development, please take a look to Connectors development dedicated page.</p>"},{"location":"development/platform/#production-build","title":"Production build","text":"<p>Based on development source you can build the package for production. This package will be minified and optimized with esbuild.</p> <pre><code>$ cd opencti-frontend\n$ yarn build\n$ cd ../opencti-graphql\n$ yarn build\n</code></pre> <p>After the build you can start the production build with yarn serv. This build will use the production.json configuration file</p> <pre><code>$ cd ../opencti-graphql\n$ yarn serv\n</code></pre>"},{"location":"development/python/","title":"Python library","text":"<p>The PyCTI library is the official Python client for OpenCTI. It is made to help developers interact with the openCTI plaform.</p>"},{"location":"development/python/#installation","title":"Installation","text":"<p>To install the latest Python client library, please use <code>pip</code>:</p> <pre><code>$ pip3 install pycti\n</code></pre>"},{"location":"development/python/#using-the-helper-functions","title":"Using the helper functions","text":"<p>The main class <code>OpenCTIApiClient</code> contains all what you need to interact with the platform, you just have to initialize it.</p> <p>The following example shows how you create an indicator in OpenCTI using the python library with TLP marking and OpenCTI compatible date format.</p> <pre><code>from dateutil.parser import parse\nfrom pycti import OpenCTIApiClient\nfrom stix2 import TLP_GREEN\n\n# OpenCTI API client initialization\nopencti_api_client = OpenCTIApiClient(\"https://myopencti.server\", \"mysupersecrettoken\")\n\n# Define an OpenCTI compatible date\ndate = parse(\"2019-12-01\").strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n\n# Get the OpenCTI marking for stix2 TLP_GREEN\nTLP_GREEN_CTI = opencti_api_client.marking_definition.read(id=TLP_GREEN[\"id\"])\n\n# Use the client to create an indicator in OpenCTI\nindicator = opencti_api_client.indicator.create(\n    name=\"C2 server of the new campaign\",\n    description=\"This is the C2 server of the campaign\",\n    pattern_type=\"stix\",\n    pattern=\"[domain-name:value = 'www.5z8.info']\",\n    x_opencti_main_observable_type=\"IPv4-Addr\",\n    valid_from=date,\n    update=True,\n    markingDefinitions=[TLP_GREEN_CTI[\"id\"]],\n)\n</code></pre>"},{"location":"development/python/#examples","title":"Examples","text":"<p>A suite of illustrative examples is available in the PyCTI GitHub repository to aid in better understanding.</p>"},{"location":"reference/api/","title":"GraphQL API","text":"<p>OpenCTI provides a comprehensive API based on GraphQL, allowing users to perform various actions programmatically. The API enables users to interact with OpenCTI's functionality and data, offering a powerful tool for automation, integration, and customization. All actions that can be performed through the platform's graphical interface are also achievable via the API.</p>"},{"location":"reference/api/#authentication","title":"Authentication","text":"<p>Access to the OpenCTI API requires authentication using standard authentication mechanisms. Access rights to data via the API will be determined by the access privileges of the user associated with the API key. For authentication, users need to include the following headers in their API requests:</p> <pre><code>Content-Type: application/json\nAuthorization: Bearer [API key]\n</code></pre>"},{"location":"reference/api/#documentation","title":"Documentation","text":"<p>The OpenCTI API consists of various endpoints corresponding to different functionalities and operations within the platform. These endpoints allow users to perform actions such as querying data, creating or updating entities, and more. Users can refer to the Understand GraphQL section to understand how it works.</p> <p>Documentation for the OpenCTI API, including schema definitions, the list of filters available and queryable fields, is available through the OpenCTI platform. It can be found on the GraphQL playground. However, query examples and mutation examples are not yet available. In the meantime, users can explore the available endpoints and their functionality by inspecting network traffic in the browser's developer tools or by examining the source code of the Python client.</p> <p></p> <p></p>"},{"location":"reference/api/#understand-graphql","title":"Understand GraphQL","text":"<p>GraphQL is a powerful query language for APIs that enables clients to request exactly the data they need. Unlike traditional REST APIs, which expose fixed endpoints and return predefined data structures, GraphQL APIs allow clients to specify the shape and structure of the data they require.</p>"},{"location":"reference/api/#core-concepts","title":"Core concepts","text":""},{"location":"reference/api/#schema-definition-language-sdl","title":"Schema Definition Language (SDL)","text":"<p>GraphQL APIs are defined by a schema, which describes the types of data that can be queried and the relationships between them. The schema is written using the Schema Definition Language (SDL), which defines types, fields, and their relationships.</p>"},{"location":"reference/api/#query-language","title":"Query language","text":"<p>GraphQL uses a query language to request data from the server. Clients can specify exactly which fields they need and how they are related, enabling precise data retrieval without over-fetching or under-fetching.</p> <p>Example:</p> <pre><code>query IntrusionSets {\n    intrusionSets (\n        filters:\n        {\n            mode: and,\n            filters: [\n                {\n                    key: \"name\",\n                    values: [\"Ajax Security Team\"],\n                    operator: eq,\n                    mode: or,\n                }\n            ],\n            filterGroups: [],\n        }\n    )\n    {\n        edges{\n            node{\n                id\n                name\n                description\n                externalReferences{\n                    edges{\n                        node{\n                            url\n                            source_name\n                        }\n                    }\n                }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"reference/api/#resolvers","title":"Resolvers","text":"<p>Resolvers are functions responsible for fetching the requested data. Each field in the GraphQL schema corresponds to a resolver function, which determines how to retrieve the data from the underlying data sources.</p>"},{"location":"reference/api/#how-it-works","title":"How it Works","text":"<ol> <li>Schema definition: The API provider defines a GraphQL schema using SDL, specifying the types and fields available for querying.</li> <li>Query execution: Clients send GraphQL queries to the server, specifying the data they need. The server processes the query, resolves each field, and constructs a response object with the requested data.</li> <li>Validation and execution: The server validates the query against the schema to ensure it is syntactically and semantically correct. If validation passes, the server executes the query, invoking the appropriate resolver functions to fetch the requested data.</li> <li>Data retrieval: Resolvers fetch data from the relevant data sources, such as databases, APIs, or other services. They transform the raw data into the shape specified in the query and return it to the client.</li> <li>Response formation: Once all resolvers have completed, the server assembles the response object containing the requested data and sends it back to the client.</li> </ol>"},{"location":"reference/api/#external-resources","title":"External Resources","text":"<p>For a more in-depth understanding of GraphQL and its usage, consider exploring the following external resources:</p> <ul> <li>GraphQL Official Documentation</li> <li>GraphQL query documentation</li> <li>How to GraphQL</li> </ul>"},{"location":"reference/data-intelligence/","title":"Data intelligence","text":"<p>As a cyber threat intelligence platform, OpenCTI offers functionalities that enable users to move quickly from raw data to operational intelligence by building up high-quality, structured information.</p> <p>To do so, the platform provides a number of essential capabilities, such as automated data deduplication, merging of similar entities while preserving relationship integrity, the ability to modulate the confidence levels on your intelligence, and the presence of inference rules to automate the creation of logical relationships among your data.</p> <p>The purpose of this page is to list the features of the platform that contribute to the intelligibility and quality of intelligence.</p>"},{"location":"reference/data-intelligence/#deduplication","title":"Deduplication","text":"<p>The first essential data intelligence mechanism in OpenCTI is the deduplication of information and relations.</p> <p>This advanced functionality not only enables you to check whether a piece of data, information or a relationship is not a duplicate of an existing element, but will also, under certain conditions, enrich the element already present.</p> <p>If the new duplicated entity has new content, the pre-existing entity can be enriched with the new information from the duplicate.</p> <p>It works as follows (see details in the dedicated page):</p> <ul> <li>For entities: based on the entity's properties based on a specific ID generated by the \"ID Contributing Properties\" platform (properties listed on the dedicated page).</li> <li>For relationships: based on type, source, target, start time, and stop time.</li> <li>For observables: a specific ID is also generated by the platform, this time based on the specifications of the STIX model.</li> </ul> <p>The ability to update and enrich is determined by the confidence level and quality level of the entities and relationships (see diagram on page deduplication).</p>"},{"location":"reference/data-intelligence/#merging","title":"Merging","text":"<p>OpenCTI's merging function is one of the platform's crucial data intelligence elements.</p> <p>From the Data &gt; Entities tab, this feature lets you merge up to 4 entities of the same type. A parent entity is selected and assigned up to three child entities.</p> <p>The benefit of this feature is to centralize a number of similar elements from different sources without losing data or degrading the quality of the information. During merging, the platform will create relationships to anchor all the data to the consolidated entity.</p> <p>This enrichment function consolidates the data and avoids duplication, but above all initiates a structured intelligence process while preserving the integrity of pre-existing relationships as presented here.</p>"},{"location":"reference/data-intelligence/#confidence-level-and-data-segregation","title":"Confidence level and data segregation","text":"<p>Another key element of OpenCTI's data intelligence is its ability to apply confidence levels and to segregate the data present in the platform.</p> <p>The confidence level is directly linked to users and Role Based Access Control. It is applied to a user directly or indirectly via the confidence level of the group to which the user belongs. This element is fundamental as it defines the levels of data manipulation to which the user (real or connector) is entitled.</p> <p>The correct application of confidence levels is all the more important as it will determine the confidence level of the data manipulated by a user. It is therefore a decisive mechanism, since it underpins the confidence you have in the content of your instance.</p> <p>While it is important to apply a level of trust to your users or groups, it is also important to define a way of categorizing and protecting your data.</p> <p>Data segregation makes it possible to apply marking definitions and therefore establish a standardized framework for classifying data.</p> <p>These marking definitions, like the classic Traffic Light Protocols (TLP) implemented by default in the platform, will determine whether a user can access a specific data set. The marking will be applied at the group level to which the user belongs, which will determine the data to which the user has access and therefore the data that the user can potentially handle.</p>"},{"location":"reference/data-intelligence/#inference-rules","title":"Inference rules","text":"<p>In OpenCTI, data intelligence is not just about the ability to segregate, qualify or enrich data. OpenCTI's inference rules enable you to mobilize the data on your platform effectively and operationally.</p> <p>These predefined rules enable the user to speed up cyber threat management. For example, inferences can be used to automatically identify incidents based on a sighting, to create sightings on observables based on new observed data, to propagate relationships based on an observable, etc.</p> <p>In all, the platform includes some twenty high-performance inference rules that considerably speed up the analysis and response to threats (see the full list here).</p> <p>These rules are based on a logical interpretation of the data, resulting in a pre-analysis of the information by creating relationships that will enrich the intelligence in the platform. There are three main benefits: efficiency, completeness and accuracy. These user benefits can be found here.</p> <p>Note: If these rules are present in the platform, they are not activated by default.</p> <p>Once activated, they scan all the data in your platform in the background to identify all the existing relationships that meet the conditions of the rules. Then, the rules operate continuously to create relationships. If you deactivate a rule, all the objects and relationships it has created will be deleted.</p> <p>These actions can only be carried out by an administrator of the instance.</p>"},{"location":"reference/data-model/","title":"Data model","text":"<p>Under construction</p> <p>This page will be automatically generated to reference the platform's data model. We are doing our best to implement this automatic generation as quickly as possible.</p>"},{"location":"reference/filters-migration/","title":"Filters format migration for OpenCTI 5.12","text":"<p>The version 5.12 of OpenCTI introduces breaking changes to the filters format 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.</p>"},{"location":"reference/filters-migration/#why-this-migration","title":"Why this migration?","text":"<p>Before OpenCTI 5.12, it was not possible to construct complex filters combinations: we couldn't embed filters within filters, used different boolean modes (and/or), filter on all available attributes or relations for a given entity type, or even test for empty fields of any sort.</p> <p>Legacy of years of development, the former format and filtering mechanics were not adapted for such task, and a profound refactoring was necessary to make it happen.</p> <p>Here are the main pain points we identified beforehand:</p> <ul> <li>The filters frontend and backend formats were very different, requiring careful conversions.</li> <li>The filter were static lists of keys, depending on each given entity type and maintained by hands.</li> <li>The operator (<code>eq</code>, <code>not_eq</code>, etc.) was inside the key (e.g. <code>entity_type_not_eq</code>), limiting operator combination and requiring error-prone parsing.</li> <li>The frontend format imposed a unique form of combination (<code>and</code> between filters, <code>or</code> between values inside each filter, and nothing else possible).</li> <li>The flat list structure made impossible filter imbrication by nature.</li> <li>Filters and query options were mixed in GQL queries for the same purpose (for instance, option <code>types</code> analog to a filter on key <code>entity_type</code>).</li> </ul> <pre><code>// filter formats in OpenCTI &lt; 5.12\n\ntype Filter = {\n    key: string, // a key in the list of the available filter keys for given the entity type\n    values: string[],\n    operator: string,\n    filterMode: 'and' | 'or',\n}\n\n// \"give me Reports labelled with labelX or labelY\"\nconst filters = [\n  { \n    \"key\": \"entity_type\",\n    \"values\": [\"Report\"],\n    \"operator\": \"eq\",\n    \"filterMode\": \"or\"\n  },\n  { \n    \"key\": \"labelledBy\",\n    \"values\": [\"&lt;id-for-labelX&gt;\", \"&lt;id-for-labelY&gt;\"],\n    \"operator\": \"eq\",\n    \"filterMode\": \"or\"\n  },\n]\n</code></pre> <p>The new format brings a lot of short-term benefits and is compatible with our long-term vision of the filtering capabilities in OpenCTI. We chose a simple recursive structure that allow complex combination of any sort with respect to basic boolean logic.</p> <p>The list of operator is fixed and can be extended during future developments.</p> <pre><code>// filter formats in OpenCTI &gt;= 5.12\n\ntype FilterGroup = {\n  mode: 'and' | 'or'\n  filters: Filter[]\n  filterGroups: FilterGroup[] // recursive definition\n}\n\ntype Filter  = {\n  key: string[]\n  values: string[]\n  operator: 'eq' | 'not_eq' | 'gt' // ... and more\n  mode: 'and' | 'or',\n}\n\n// \"give me Reports and RFIs, not marked TLP:RED with labelX or no label\"\nconst filters = {\n  mode: 'and',\n  filters: [\n    { key: 'entity_type', values: ['Report', 'Case-Rfi'], operator: 'eq', mode: 'or', },\n    { key: 'objectMarking', values: ['&lt;id-for-TLP:RED&gt;'], operator: 'not_eq', mode: 'or', },\n  ],\n  filterGroups: [{\n    mode: 'or',\n    filters: [\n      { key: 'objectLabel', values: [\"&lt;id-for-labelX&gt;\"], operator: 'eq', mode: 'or', },\n      { key: 'objectLabel', values: [], operator: 'nil', mode: 'or', },\n    ],\n    filterGroups: [],\n  }],\n};\n</code></pre> <p>Because changing filters format impacts almost everything in the platform, we decided to do a complete refactoring once and for all. We want this migration process to be clear and easy.</p>"},{"location":"reference/filters-migration/#what-has-been-changed","title":"What has been changed","text":"<p>The new filter implementation bring major changes in the way filters are processed and executed.</p> <ul> <li> <p>We change the filters formats (see <code>FilterGroup</code> type above):</p> <ul> <li>In the frontend, an operator and a mode are stored for each key.</li> <li>The new format enables filters imbrication thanks to the new attribute 'filterGroups'.</li> <li>The keys are of type string (no more static list of enums).</li> <li>The 'values' attribute can no longer contain null values (use the <code>nil</code> operator instead).</li> </ul> </li> <li> <p>We also renamed some filter keys, to be consistent with the entities schema definitions.</p> </li> <li>We implemented the handling of the different operators and modes in the backend.</li> <li>We introduced new void operators (<code>nil</code> / <code>not_nil</code>) to test the presence or absence of value in any field.</li> </ul>"},{"location":"reference/filters-migration/#how-to-migrate-your-own-filters","title":"How to migrate your own filters","text":"<p>We wrote a migration script to convert all stored filters created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform.</p> <p>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 &gt;= 5.12.</p>"},{"location":"reference/filters-migration/#filter-conversion","title":"Filter conversion","text":"<p>To convert filters prior to version 5.12 in the new format:</p> <ol> <li>update the <code>key</code> field if it has been changed in 5.12 (see the conversion table below),</li> <li>rename the field <code>filterMode</code> in <code>mode</code></li> <li>if <code>values</code> contains <code>null</code>, see below for conversion.</li> </ol> <p>Now you can build your new <code>FilterGroup</code> object with:</p> <ul> <li><code>mode: 'and'</code></li> <li><code>filters</code> = array of converted filters (following previous steps),</li> <li><code>filterGroups: []</code></li> </ul> <pre><code>const oldFilter = {\n    key: 'old_key',\n    values: ['value1', 'value2'],\n    operator: 'XX',\n    filterMode: 'XX',\n}\n\nconst convertedFilter = {\n    key: 'converted_key_if_necessary',\n    values: ['value1', 'value2'],\n    operator: 'XX',\n    mode: 'XX',\n}\n\nconst newFilters = {\n    mode: 'and',\n    filters: [convertedFilter1, convertedFilter2...], // array with all converted filters\n    filterGroups: [],\n}\n</code></pre> <p>If <code>values</code> contains a <code>null</code> value, you need to convert the filter by using the new <code>nil</code> / <code>not_nil</code> operators. Here's the procedure:</p> <ol> <li> <p>Extract one filter dedicated to <code>null</code></p> <ul> <li>if operator was <code>'eq'</code>, switch to <code>operator: 'nil'</code> / if operator was <code>not_eq</code>, switch to <code>operator = 'not_nil'</code></li> <li><code>values = []</code></li> </ul> </li> <li> <p>Extract another filter for all the other values.</p> </li> </ol> <pre><code>// \"Must have a label that is not Label1 or Label2\"\nconst oldFilter = {\n    key: 'labelledBy',\n    values: [null, 'id-for-Label1', 'id-for-Label2'],\n    operator: 'not_eq',\n    filterMode: 'and',\n}\n\nconst newFilters = {\n    mode: 'and',\n    filters: [\n      {\n        key: 'objectLabel',\n        values: ['id-label-1', 'id-for-Label2'],\n        operator: 'not_eq',\n        mode: 'and',\n      },\n      {\n        key: 'objectLabel',\n        values: [],\n        operator: 'not_nil',\n        mode: 'and',\n      },\n    ],\n    filterGroups: [],\n}\n</code></pre> <p>Switch to nested filter to preserve logic</p> <p>To preserve the logic of your old filter you might need to compose nested filter groups. This could happen for instance when using <code>eq</code> operator with <code>null</code> values for one filter, combined in <code>and</code> mode with other filters.</p> <p></p>"},{"location":"reference/filters-migration/#filter-keys-conversion-table","title":"Filter keys conversion table","text":"<p>Make sure you address all the filter keys that require conversion, following the map below:</p> <pre><code>// array of [oldKey, newKey] for the renamed keys\nconst keyConversion = [\n    ['labelledBy', 'objectLabel'],\n    ['markedBy', 'objectMarking'],\n    ['objectContains', 'objects'],\n    ['killChainPhase', 'killChainPhases'],\n    ['assigneeTo', 'objectAssignee'],\n    ['participant', 'objectParticipant'],\n    ['creator', 'creator_id'],\n    ['hasExternalReference', 'externalReferences'],\n    ['hashes_MD5', 'hashes.MD5'],\n    ['hashes_SHA1', 'hashes.SHA-1'],\n    ['hashes_SHA256', 'hashes.SHA-256'],\n    ['hashes_SHA512', 'hashes.SHA-512']\n]\n</code></pre>"},{"location":"reference/filters-migration/#examples","title":"Examples","text":""},{"location":"reference/filters-migration/#simple-example","title":"Simple example","text":"<p>Let's start with a simple case:</p> <p>All Reports with label \"label1\" or \"label2\"</p> <p><code>(entity_type = Report) AND (label = label1 OR label2)</code></p> <pre><code>const oldBackendFilter = [\n  {\n    key: 'entity_type',\n    values: ['Report'],\n    operator: 'eq',\n    filterMode: 'or',\n  },\n  {\n   key: 'labelledBy',\n    values: [label1_id, label2_id],\n    operator: 'eq',\n    filterMode: 'or',\n  },\n];\n\nconst newFilters = {\n  mode: 'and',\n  filters: [\n    {\n      key: 'entity_type',\n      values: ['Report'],\n      operator: 'eq',\n      mode: 'or',\n    },\n    {\n      key: 'objectLabel',\n      values: [label1_id, label2_id],\n      operator: 'eq',\n      mode: 'or',\n    }\n  ],\n  filterGroups: [],\n};\n</code></pre>"},{"location":"reference/filters-migration/#complex-example","title":"Complex example","text":"<p>Now let's see a more complex case involving filter group nesting:</p> <p>\"All Reports that have either the label \"label1\" or \"label2\", or no label at all\"</p> <p><code>(entity_type = Report) AND (label = \"No label\" OR label1 OR label2)</code></p> <pre><code>const oldBackendFilter = [\n    {\n      key: 'labelledBy',\n      values: [label1_id, label2_id, null],\n      operator: 'eq',\n      filterMode: 'or',\n    },\n    {\n      key: 'entity_type',\n      values: ['Report'],\n      operator: 'eq',\n      filterMode: 'or',\n    },\n];\n\nconst newFilters = {\n    mode: 'and',\n    filters: [\n      {\n        key: 'entity_type',\n        values: ['Report'],\n        operator: 'eq',\n        mode: 'or',\n      },\n    ],\n    // the combination mode/operator in this case requires nested filter groups\n    filterGroups: [\n      {\n        mode: 'or',\n        filters: [\n          {\n            key: 'objectLabel',\n            values: [label1_id, label2_id],\n            operator: 'eq',\n            mode: 'or',\n          },\n          {\n            key: 'objectLabel',\n            operator: 'nil',\n            values: [], // empty, does not matter\n            mode: 'or', // and/or, does not matter \n          },\n        ],\n        filterGroups: [],\n      }\n    ],\n};\n</code></pre>"},{"location":"reference/filters-migration/#residual-dynamic-filters","title":"Residual dynamic filters","text":"<p>Dynamic filters are not stored in the database, they enable to filter view in the UI, e.g. filters in entities list, investigations, knowledge graphs. They are saved as URL parameters, and can be saved in local storage.</p> <p>These filters are not migrated automatically and are lost when moving to 5.12. This concerns the filters saved for each view, that are restored when coming back to the same view. You will need to reconstruct the filters by hand in the UI; these new filters will be properly saved and restored afterward.</p> <p>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.</p> <p></p>"},{"location":"reference/filters/","title":"Filter knowledge","text":"<p>In OpenCTI, you can filter data to target or view entities that have particular attributes.</p>"},{"location":"reference/filters/#filters-usages","title":"Filters usages","text":"<p>There are two types of filters that are used in many locations in the platform:</p> <ul> <li>in entities lists: to display only the entities matching the filters. If an export or a background task is generated, only the filtered data will be taken into account,</li> <li>in investigations and knowledge graphs: to display only the entities matching the filters,</li> <li>in dashboards: to create widget with only the entities matching the filters,</li> <li>in feeds, TAXII collections, triggers, streams, playbooks, background tasks: to process only the data or events matching the filters.</li> </ul>"},{"location":"reference/filters/#dynamic-filters","title":"Dynamic filters","text":"<p>Dynamic filters are not stored in the database, they enable to filter view in the UI, e.g. filters in entities list, investigations, knowledge graphs.</p> <p>However, they are still persistent in the platform frontend side. The filters used in a view are saved as URL parameters, so you can save and share links of these filtered views.</p> <p>Also, your web browser saves in local storage the filters that you are setting in various places of the platform, allowing to retrieve them when you come back to the same view. You can then keep working from where you left of.</p> <p></p> <p></p>"},{"location":"reference/filters/#stored-filters","title":"Stored filters","text":"<p>Stored filters are attributes of an entity, and are therefore stored in the database. They are stored as an attribute in the object itself, e.g. filters in dashboards, feeds, TAXII collections, triggers, streams, playbooks.</p>"},{"location":"reference/filters/#create-a-filter","title":"Create a filter","text":"<p>To create a filter, add every key you need using the 'Add filter' select box. It will give you the possible attributes on which you can filter in the current view.</p> <p>A grey box appears and allows to select:</p> <ol> <li>the operator to use, and</li> <li>the values to compare (if the operator is not \"empty\" or \"not_empty\").</li> </ol> <p>You can add as many filters as you want, even use the same key twice with different operators and values.</p> <p>The boolean modes (and/or) are either global (between every attribute filters) or local (between values inside a filter). Both can be switched with a single click, changing the logic of your filtering.</p>"},{"location":"reference/filters/#filters-format","title":"Filters format","text":"<p>Since OpenCTI 5.12, the OpenCTI platform uses a new filter format called <code>FilterGroup</code>. The <code>FilterGroup</code> model enables to do complex filters imbrication with different boolean operators, which extends greatly the filtering capabilities in every part of the platform.</p>"},{"location":"reference/filters/#structure","title":"Structure","text":"<p>The new format used internally by OpenCTI and exposed through its API, can be described as below:</p> <pre><code>// filter formats in OpenCTI &gt;= 5.12\n\ntype FilterGroup = {\n  mode: 'and' | 'or'\n  filters: Filter[]\n  filterGroups: FilterGroup[] // recursive definition\n}\n\ntype Filter  = {\n  key: string[] // or single string (input coercion)\n  values: string[]\n  operator: 'eq' | 'not_eq' | 'gt' // ... and more\n  mode: 'and' | 'or',\n}\n</code></pre>"},{"location":"reference/filters/#properties","title":"Properties","text":"<p>In a given filter group, the <code>mode</code> (<code>and</code> or <code>or</code>) represents the boolean operation between the different <code>filters</code> and <code>filterGroups</code> arrays. The <code>filters</code> and <code>filterGroups</code> arrays are composed of objects of type Filter and FilterGroup.</p> <p>The <code>Filter</code> has 4 properties:</p> <ul> <li>a <code>key</code>, representing the kind of data we want to target (example: <code>objectLabel</code> to filter on labels or <code>createdBy</code> to filter on the author),</li> <li>an array of <code>values</code>, representing the values we want to compare to,</li> <li>an <code>operator</code> representing the operation we want to apply between the <code>key</code> and the <code>values</code>,</li> <li>a <code>mode</code> (<code>and</code> or <code>or</code>) to apply between the values if there are several ones.</li> </ul>"},{"location":"reference/filters/#operators","title":"Operators","text":"<p>The available operators are:</p> Value Meaning Additional information eq equal not_eq different gl greater than against textual values, the alphabetical ordering is used gte greater than or equal against textual values, the alphabetical ordering is used lt lower than against textual values, the alphabetical ordering is used lte lower than or equal against textual values, the alphabetical ordering is used nil empty / no value <code>nil</code> do not require anything inside <code>values</code> not_nil non-empty / any value <code>not_nil</code> do not require anything inside <code>values</code> <p>In addition, there are operators:</p> <ul> <li><code>starts_with</code> / <code>not_starts_with</code> / <code>ends_with</code> / <code>not_ends_with</code> / <code>contains</code> / <code>not contains</code>, available for searching in short string fields (name, value, title, etc.),</li> <li><code>search</code>, available in short string and text fields.</li> </ul> <p>There is a small difference between <code>search</code> and <code>contains</code>. <code>search</code> finds any occurrence of specified words, regardless of order, while \"contains\" specifically looks for the exact sequence of words you provide.</p> <p>Always use single-key filters</p> <p>Multi-key filters are not supported across the platform and are reserved to specific, internal cases.</p>"},{"location":"reference/filters/#examples","title":"Examples","text":"<p>entity_type = 'Report'</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [{\n        key: 'entity_type',\n        values: ['Report'],\n        operator: 'eq',\n        mode: 'or', // useless here because values contains only one value\n    }],\n    filterGroups: [],\n};\n</code></pre> <p>(entity_type = 'Report') AND (label = 'label1' OR 'label2')</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [\n        {\n            key: 'entity_type',\n            values: ['Report'],\n            operator: 'eq',\n            mode: 'or',\n        },\n        {\n            key: 'objectLabel',\n            values: ['label1', 'label2'],\n            operator: 'eq',\n            mode: 'or',\n        }\n    ],\n    filterGroups: [],\n};\n</code></pre> <p>(entity_type = 'Report') AND (confidence &gt; 50 OR marking is empty)</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [\n        {\n            key: 'entity_type',\n            values: ['Report'],\n            operator: 'eq',\n            mode: 'or',\n        }\n    ],\n    filterGroups: [\n        {\n            mode: 'or',\n            filters: [\n                {\n                    key: 'confidence',\n                    values: ['50'],\n                    operator: 'gt',\n                    mode: 'or',\n                },\n                {\n                    key: 'objectMarking',\n                    values: [],\n                    operator: 'nil',\n                    mode: 'or',\n                },\n            ],\n            filterGroups: [],\n        }\n    ],\n};\n</code></pre>"},{"location":"reference/filters/#keys","title":"Keys","text":""},{"location":"reference/filters/#filter-keys-validation","title":"Filter keys validation","text":"<p>Only a specific set of key can be used in the filters.</p> <p>Automatic key checking prevents typing error when constructing filters via the API. If a user write an unhandled key (<code>object-label</code> instead of <code>objectLabel</code> for instance), the API will return an error instead of an empty list. Doing so, we make sure the platform do not provide misleading results.</p>"},{"location":"reference/filters/#regular-filter-keys","title":"Regular filter keys","text":"<p>For an extensive list of available filter keys, refer to the attributes and relations schema definitions.</p> <p>Here are some of the most useful keys as example. NB: X refers here to the filtered entities.</p> <ul> <li><code>objectLabel</code>: label applied on X,</li> <li><code>objectMarking</code>: marking applied on X,</li> <li><code>createdBy</code>: author of X,</li> <li><code>creator_id</code>: technical creator of X,</li> <li><code>created_at</code>: date of creation of X in the platform,</li> <li><code>confidence</code>: confidence of X,</li> <li><code>entity_type</code>: entity type of X ('Report', 'Stix-Cyber-Observable', ...),</li> </ul>"},{"location":"reference/filters/#special-filter-keys","title":"Special filter keys","text":"<p>Some keys do not exist in the schema definition, but are allowed in addition. They describe a special behavior.</p> <p>It is the case for:</p> <ul> <li><code>sightedBy</code>: entities to which X is linked via a STIX sighting relationship,</li> <li><code>workflow_id</code>: status id of the entities, or status template id of the status of the entities,</li> <li><code>representative</code>: entities whose representative (name for reports, value for some observables, composition of the source and target names for a relationship...) matches the filter,</li> <li><code>connectedToId</code>: the listened instances for an instance trigger.</li> </ul> <p>For some keys, negative equality filtering is not supported yet (<code>not_eq</code> operator). For instance, it is the case for:</p> <ul> <li><code>fromId</code></li> <li><code>fromTypes</code></li> <li><code>toId</code></li> <li><code>toTypes</code></li> </ul> <p>The <code>regardingOf</code> filter key has a special format and enables to target the entities having a relationship of a certain type with certain entities. Here is an example of filter to fetch the entities related to the entity X:</p> <pre><code>filters = {\n  mode: 'and',\n  filters: [\n    {\n      key: 'regardingOf',\n      values: [\n        { key: 'id', values: ['id-of-X'] },\n        { key: 'relationship_type', values: ['related-to'] },\n      ],\n    },\n  ],\n  filterGroups: [],\n};\n</code></pre>"},{"location":"reference/filters/#limited-support-in-stream-events-filtering","title":"Limited support in stream events filtering","text":"<p>Filters that are run against the event stream are not using the complete schema definition in terms of filtering keys.</p> <p>This concerns:</p> <ul> <li>Live streams,</li> <li>CSV feeds,</li> <li>TAXII collection,</li> <li>Triggers,</li> <li>Playbooks.</li> </ul> <p>For filters used in this context, only some keys are supported for the moment:</p> <ul> <li><code>confidence</code></li> <li><code>objectAssignee</code></li> <li><code>createdBy</code></li> <li><code>creator</code></li> <li><code>x_opencti_detection</code></li> <li><code>indicator_types</code></li> <li><code>objectLabel</code></li> <li><code>x_opencti_main_observable_type</code></li> <li><code>objectMarking</code></li> <li><code>objects</code></li> <li><code>pattern_type</code></li> <li><code>priority</code></li> <li><code>revoked</code></li> <li><code>severity</code></li> <li><code>x_opencti_score</code></li> <li><code>entity_type</code></li> <li><code>x_opencti_workflow_id</code></li> <li><code>connectedToId</code> (for the instance triggers)</li> <li><code>fromId</code> (the instance in the \"from\" of a relationship)</li> <li><code>fromTypes</code> (the entity type in the \"from\" of a relationship)</li> <li><code>toId</code> (the instance in the \"to\" of a relationship)</li> <li><code>toTypes</code> (the entity type in the \"to\" of a relationship)</li> </ul>"},{"location":"reference/fips/","title":"SSL FIPS 140-2 deployment","text":""},{"location":"reference/fips/#introduction","title":"Introduction","text":"<p>For organizations that need to deploy OpenCTI in a SSL FIPS 140-2 compliant environment, we provide FIPS compliant OpenCTI images for all components of the platform. Please note that you will also need to deploy dependencies (ElasticSearch / OpenSearch, Redis, etc.) with FIPS 140-2 SSL to have the full compliant OpenCTI technological stack.</p> <p>OpenCTI SSL FIPS 140-2 compliant builds</p> <p>The OpenCTI platform, workers and connectors SSL FIPS 140-2 compliant images are based on packaged Alpine Linux with OpenSSL 3 and FIPS mode enabled maintened by the Filigran engineering team.</p>"},{"location":"reference/fips/#dependencies","title":"Dependencies","text":""},{"location":"reference/fips/#aws-native-services-in-fedramp-compliant-environment","title":"AWS Native Services in FedRAMP compliant environment","text":"<p>It is important to remind that OpenCTI is fully compatible with AWS native services and all dependencies are available in both FedRAMP Moderate (East / West) and FedRAMP High (GovCloud) scopes.</p> <ul> <li>Amazon OpenSearch Service (OpenSearch)</li> <li>Amazon ElastiCache (Redis)</li> <li>Amazon MQ (RabbitMQ)</li> <li>Amazon Simple Storage Service (S3 bucket)</li> </ul>"},{"location":"reference/fips/#elasticsearch-opensearch","title":"ElasticSearch / OpenSearch","text":"<p>ElasticSearch is known to be compatible with FIPS 140-2 SSL using the proper JVM. There is a comprehensive guide in the Elastic documentation.</p> <p>Alternatively, please note that Elastic is also providing an ElasticSearch FedRAMP authorized cloud offering.  </p>"},{"location":"reference/fips/#redis","title":"Redis","text":"<p>Redis does not provide FIPS 140-2 SSL compliant Docker images but supports very well custom tls-ciphersuites that can be configured to use the system FIPS 140-2 OpenSSL library. </p> <p>Alternatively, you can use a Stunnel TLS endpoint to ensure encrypted communication between OpenCTI and Redis. There are a few examples available, here or here.</p>"},{"location":"reference/fips/#rabbitmq","title":"RabbitMQ","text":"<p>RabbitMQ does not provide FIPS 140-2 SSL compliant Docker images but, as Redis, supports custom cipher suites. Also, it is confirmed since RabbitMQ version 3.12.5, the associated Erlang build (&gt; 26.1), supports FIPS mode on OpenSSL 3.</p> <p>Alternatively, you can use a Stunnel TLS endpoint to ensure encrypted communication between OpenCTI and RabbitMQ.</p>"},{"location":"reference/fips/#s3-bucket-minio","title":"S3 Bucket / MinIO","text":"<p>If you cannot use an S3 endpoint already deployed in your FIPS 140-2 SSL compliant environment, MinIO provides FIPS 140-2 SSL compliant Docker images which then are very easy to deploy within your environment.</p>"},{"location":"reference/fips/#opencti-stack","title":"OpenCTI stack","text":""},{"location":"reference/fips/#platform","title":"Platform","text":"<p>For the platform, we provide FIPS 140-2 SSL compliant Docker images. Just use the appropriate tag to ensure you are deploying the FIPS compliant version and follow the standard Docker deployment procedure. </p>"},{"location":"reference/fips/#worker","title":"Worker","text":"<p>For the worker, we provide FIPS 140-2 SSL compliant Docker images. Just use the appropriate tag to ensure you are deploying the FIPS compliant version and follow the standard Docker deployment procedure.</p>"},{"location":"reference/fips/#connectors","title":"Connectors","text":"<p>All connectors have FIPS 140-2 SSL compliant Docker images. For each connector you need to deploy, please use the tag <code>{version}-fips</code> instead of <code>{version}</code> and  follow the standard deployment procedure. An example is available on Docker Hub. </p>"},{"location":"reference/streaming/","title":"Data Streaming","text":""},{"location":"reference/streaming/#presentation","title":"Presentation","text":"<p>In order to provide a real time way to consume STIX CTI information, OpenCTI provides data events in a stream that can be consumed to react on creation, update, deletion and merge. This way of getting information out of OpenCTI is highly efficient and already use by some connectors.</p>"},{"location":"reference/streaming/#technology","title":"Technology","text":""},{"location":"reference/streaming/#redis-stream","title":"Redis stream","text":"<p>OpenCTI is currently using REDIS Stream as the technical layer. Each time something is modified in the OpenCTI database, a specific event is added in the stream.</p>"},{"location":"reference/streaming/#sse-protocol","title":"SSE protocol","text":"<p>In order to provide a really easy consuming protocol we decide to provide a SSE (https://fr.wikipedia.org/wiki/Server-sent_events) HTTP URL linked to the standard login system of OpenCTI. Any user with the correct access rights can open and access http://opencti_instance/stream, and open an SSE connection to start receiving live events. You can of course consume directly the stream in Redis, but you will have to manage access and rights directly.</p>"},{"location":"reference/streaming/#events-format","title":"Events format","text":"<pre><code>id: {Event stream id} -&gt; Like 1620249512318-0\nevent: {Event type} -&gt; create / update / delete\ndata: { -&gt; The complete event data\n    version -&gt; The version number of the event\n    type -&gt; The inner type of the event\n    scope -&gt; The scope of the event [internal or external]\n    data: {STIX data} -&gt; The STIX representation of the data.\n    message -&gt; A simple string to easy understand the event\n    origin: {Data Origin} -&gt; Complex object with different information about the origin of the event\n    context: {Event context} -&gt; Complex object with meta information depending of the event type\n}\n</code></pre> <p>It can be used to consume the stream from this specific point.</p>"},{"location":"reference/streaming/#stix-data","title":"STIX data","text":"<p>The current stix data representation is based on the STIX 2.1 format using extension mechanism. Please take a look to the STIX documentation for more information.</p>"},{"location":"reference/streaming/#create","title":"Create","text":"<p>It's simply the data created in STIX format.</p>"},{"location":"reference/streaming/#delete","title":"Delete","text":"<p>It's simply the data in STIX format just before his deletion. You will also find the automated deletions in context due to automatic dependency management.</p> <pre><code>{\n  \"context\": {\n      \"deletions\": [{STIX data}]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#update","title":"Update","text":"<p>This event type publish the complete STIX data information along with patches information. Thanks to the patches, it's possible to rebuild the previous version and easily understand what happens in the update.</p> <p>Patch and reverse_patch follow the official jsonpatch specification. You can find more information on the jsonpatch page</p> <pre><code>{\n  \"context\": {\n      \"patch\": [/* patch operation object */],\n      \"reverse_patch\": [/* patch operation object */]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#merge","title":"Merge","text":"<p>Merge is a combination of an update of the merge targets and deletions of the sources. In this event you will find the same patch and reverse_patch as an update and the list of elements merged into the target in the \"sources\" attribute.</p> <pre><code>{\n  \"context\": {\n      \"patch\": [/* patch operation object */],\n      \"reverse_patch\": [/* patch operation object */],\n      \"sources\": [{STIX data}]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#stream-types","title":"Stream types","text":"<p>In OpenCTI we propose 2 types of streams.</p>"},{"location":"reference/streaming/#base-stream","title":"Base stream","text":"<p>The stream hosted in /stream url contains all the raw events of the platform, always filtered by the user rights (marking based). It's a technical stream a bit complex to used but very useful for internal processing or some specific connectors like backup/restore.</p> <p>This stream is live by default but if, you want to catchup, you can simply add the <code>from</code> parameter to your query. This parameter accept a timestamp in millisecond and also an event id, e.g. <code>http://localhost/stream?from=1620249512599</code></p> <p>Stream size?</p> <p>The raw stream is really important in the platform and needs te be sized according to the period of retention you want to ensure. More retention you will have, more security about reprocessing the past information you will get. We usually recommand 1 month of retention, that usually match 2 000 000 of events. This limit can be configured with <code>redis:trimming</code> option, please check deployment configuration page.</p>"},{"location":"reference/streaming/#live-stream","title":"Live stream","text":"<p>This stream aims to simplify your usage of the stream through the connectors, providing a way to create stream with specific filters through the UI. After creating this stream, is simply accessible from <code>/stream/{STREAM_ID}</code>.</p> <p>It's very useful for various cases of data externalization, synchronization, like SPLUNK, TANIUM...</p> <p>This stream provides different interesting mechanics:</p> <ul> <li>Stream the initial list of instances matching your filters when connecting based on main database if you use the recover parameter</li> <li>Auto dependencies resolution to guarantee the consistency of the information distributed</li> <li>Automatic events translation depending on the element segregation</li> </ul> <p>If you want to dig in about the internal behavior you can check this complete diagram:</p>"},{"location":"reference/streaming/#general-options","title":"General options","text":"<ul> <li>no-dependencies (query parameter or header, default false). Can be used to prevent the auto dependencies resolution. To be used with caution.</li> <li>listen-delete (query parameter or header, default true). Can be used prevent receive deletion events. To be used with caution.</li> <li>with-inferences (query parameter or header, default false). Can be used to add inferences events (from rule engine) in the stream.</li> </ul>"},{"location":"reference/streaming/#from-and-recover","title":"From and Recover","text":"<p>From and recover are 2 different options that need to be explains.</p> <ul> <li>from (query parameter) is always the parameter that describe the initial date/event_id you want to start from. Can also be setup with request header from or last-event-id</li> <li>recover (query parameter) is an option that let you consume the initial event from the database and not from the stream. Can also be setup with request header recover or recover-date </li> </ul> <p>This difference will be transparent for the consumer but very important to get old information as an initial snapshot. This also let you consume information that is no longer in the stream retention period.</p> <p>The next diagram will help you to understand the concept:</p>"},{"location":"reference/taxonomy/","title":"Taxonomy","text":"<p>In OpenCTI, taxonomies serve as structured classification systems that aid in organizing and categorizing intelligence data. This reference guide provides an exhaustive description of the platform's customizable fields within the taxonomies' framework. Users can modify, add, or delete values within the available vocabularies to tailor the classification system to their specific requirements.</p> <p>For broader documentation on the taxonomies section, please consult the appropriate page.</p>"},{"location":"reference/taxonomy/#vocabularies","title":"Vocabularies","text":"<p>Default values are based on those defined in the STIX standard but can be tailored to better suit the organization's needs.</p> Name Used in Default value Account type vocabulary (account-type-ov) User account facebook, ldap, nis, openid, radius, skype, tacacs, twitter, unix, windows-domain, windows-local Attack motivation vocabulary (attack-motivation-ov) Threat actor group accidental, coercion, dominance, ideology, notoriety, organizational-gain, personal-gain, personal-satisfaction, revenge, unpredictable Attack resource level vocabulary (attack-resource-level-ov) Threat actor group club, contest, government, individual, organization, team Case priority vocabulary (case_priority_ov) Incident response P1, P2, P3, P4 Case severity vocabulary (case_severity_ov) Incident response critical, high, medium, low Channel type vocabulary (channel_type_ov) Channel Facebook, Twitter Collection layers vocabulary (collection_layers_ov) Data source cloud-control-plane, container, host, network, OSINT Event type vocabulary (event_type_ov) Event conference, financial, holiday, international-summit, local-election, national-election, sport-competition Eye color vocabulary (eye_color_ov) Threat actor individual black, blue, brown, green, hazel, other Gender vocabulary (gender_ov) Threat actor individual female, male, nonbinary, other Grouping context vocabulary (grouping_context_ov) Grouping malware-analysis, suspicious-activity, unspecified Hair color vocabulary vocabulary (hair_color_ov) Threat actor individual bald, black, blond, blue, brown, gray, green, other, red Implementation language vocabulary (implementation_language_ov) Malware applescript, bash, c, c++, c#, go, java, javascript, lua, objective-c, perl, php, powershell, python, ruby, scala, swift, typescript, visual-basic, x86-32, x86-64 Incident response type vocabulary (incident_response_type_ov) Incident response data-leak, ransomware Incident severity vocabulary (incident_severity_ov) Incident critical, high, medium, low Incident type vocabulary (incident_type_ov) Incident alert, compromise, cybercrime, data-leak, information-system-disruption, phishing, reputation-damage, typosquatting Indicator type vocabulary (indicator_type_ov) Indicator anomalous-activity, anonymization, attribution, benign, compromised, malicious-activity, unknown Infrastructure type vocabulary (infrastructure_type_ov) Infrastructure amplification, anonymization, botnet, command-and-control, control-system, exfiltration, firewall, hosting-malware, hosting-target-lists, phishing, reconnaissance, routers-switches, staging, unknown, workstation Integrity level vocabulary (integrity_level_ov) Process high, medium, low, system Malware capabilities vocabulary (malware_capabilities_ov) Malware accesses-remote-machines, anti-debugging, anti-disassembly, anti-emulation, anti-memory-forensics, anti-sandbox, anti-vm, captures-input-peripherals, captures-output-peripherals, captures-system-state-data, cleans-traces-of-infection, commits-fraud, communicates-with-c2, compromises-data-availability, compromises-data-integrity, compromises-system-availability, controls-local-machine, degrades-security-software, degrades-system-updates, determines-c2-server, emails-spam, escalates-privileges, evades-av, exfiltrates-data, fingerprints-host, hides-artifacts, hides-executing-code, infects-files, infects-remote-machines, installs-other-components, persists-after-system-reboot, prevents-artifact-access, prevents-artifact-deletion, probes-network-environment, self-modifies, steals-authentication-credentials, violates-system-operational-integrity Malware result vocabulary (malware_result_ov) Malware analysis benign, malicious, suspicious, unknown Malware type vocabulary (malware_type_ov) Malware adware, backdoor, bootkit, bot, ddos, downloader, dropper, exploit-kit, keylogger, ransomware, remote-access-trojan, resource-exploitation, rogue-security-software, rootkit, screen-capture, spyware, trojan, unknown, virus, webshell, wiper, worm Marital status vocabulary (marital_status_ov) Threat actor individual annulled, divorced, domestic_partner, legally_separated, married, never_married, polygamous, separated, single, widowed Note types vocabulary (note_types_ov) Note analysis, assessment, external, feedback, internal Opinion vocabulary (opinion_ov) Opinion agree, disagree, neutral, strongly-agree, strongly-disagree Pattern type vocabulary (pattern_type_ov) Indicator eql, pcre, shodan, sigma, snort, spl, stix, suricata, tanium-signal, yara Permissions vocabulary (permissions_ov) Attack pattern Administrator, root, User Platforms vocabulary (platforms_ov) Data source android, Azure AD, Containers, Control Server, Data Historian, Engineering Workstation, Field Controller/RTU/PLC/IED, Google Workspace, Human-Machine Interface, IaaS, Input/Output Server, iOS, linux, macos, Office 365, PRE, SaaS, Safety Instrumented System/Protection Relay, windows Processor architecture vocabulary (processor_architecture_ov) Malware alpha, arm, ia-64, mips, powerpc, sparc, x86, x86-64 Reliability vocabulary (reliability_ov) Report, Organization A - Completely reliable, B - Usually reliable, C - Fairly reliable, D - Not usually reliable, E - Unreliable, F - Reliability cannot be judged Report types vocabulary (report_types_ov) Report internal-report, threat-report Request for information types vocabulary (request_for_information_types_ov) Request for information none Request for takedown types vocabulary (request_for_takedown_types_ov) Request for takedown brand-abuse, phishing Service status vocabulary (service_status_ov) Process SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED, SERVICE_RUNNING, SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_STOPPED Service type vocabulary (service_type_ov) Process SERVICE_FILE_SYSTEM_DRIVER, SERVICE_KERNEL_DRIVER, SERVICE_WIN32_OWN_PROCESS, SERVICE_WIN32_SHARE_PROCESS Start type vocabulary (start_type_ov) Process SERVICE_AUTO_START, SERVICE_BOOT_START, SERVICE_DEMAND_START, SERVICE_DISABLED, SERVICE_SYSTEM_ALERT Threat actor group role vocabulary (threat_actor_group_role_ov) Threat actor group agent, director, independent, infrastructure-architect, infrastructure-operator, malware-author, sponsor Threat actor group sophistication vocabulary (threat_actor_group_sophistication_ov) Threat actor group advanced, expert, innovator, intermediate, minimal, none, strategic Threat actor group type vocabulary (threat_actor_group_type_ov) Threat actor group activist, competitor, crime-syndicate, criminal, hacker, insider-accidental, insider-disgruntled, nation-state, sensationalist, spy, terrorist, unknown Threat actor individual role vocabulary (threat_actor_individual_role_ov) Threat actor individual agent, director, independent, infrastructure-architect, infrastructure-operator, malware-author, sponsor Threat actor individual sophistication vocabulary (threat_actor_individual_sophistication_ov) Threat actor individual advanced, expert, innovator, intermediate, minimal, none, strategic Threat actor individual type vocabulary (threat_actor_individual_type_ov) Threat actor individual activist, competitor, crime-syndicate, criminal, hacker, insider-accidental, insider-disgruntled, nation-state, sensationalist, spy, terrorist, unknown Tool types vocabulary (tool_types_ov) Tool credential-exploitation, denial-of-service, exploitation, information-gathering, network-capture, remote-access, unknown, vulnerability-scanning <p></p>"},{"location":"reference/taxonomy/#customization","title":"Customization","text":"<p>Users can customize the taxonomies by modifying the available values or adding new ones. These modifications enable users to adapt the classification system to their specific intelligence requirements. Additionally, within each vocabulary list, users have the flexibility to customize the order of the dropdown menu associated with the taxonomy. This feature allows users to prioritize certain values or arrange them in a manner that aligns with their specific classification needs. Additionally, users can track the usage count for each vocabulary, providing insights into the frequency of usage and helping to identify the most relevant and impactful classifications. These customization options empower users to tailor the taxonomy system to their unique intelligence requirements, enhancing the efficiency and effectiveness of intelligence analysis within the OpenCTI platform.</p> <p></p>"},{"location":"reference/usage-telemetry/","title":"Usage telemetry","text":"<p>The application collects statistical data related to its usage and performances.</p> <p>Confidentiality</p> <p>The OpenCTI platform does not collect any information related to threat intelligence knowledge which remains strictly confidential. Also, the collection is strictly anonymous and personally identifiable information is NOT collected (including IP addresses).</p> <p>All data collected is anonymized and aggregated to protect the privacy of individual users, in compliance with all privacy regulations.</p>"},{"location":"reference/usage-telemetry/#purpose-of-the-telemetry","title":"Purpose of the telemetry","text":"<p>The collected data is used for the following purposes:</p> <ul> <li>Improving the functionality and performance of the application.</li> <li>Analyzing user behavior to enhance user experience.</li> <li>Generating aggregated and anonymized statistics for internal and external reporting.</li> </ul>"},{"location":"reference/usage-telemetry/#important-thing-to-know","title":"Important thing to know","text":"<p>The platform send the metrics to the hostname <code>telemetry.filigran.io</code> using the OTLP protocol (over HTTPS). The format of the data is OpenTelemetry JSON.</p> <p>The metrics push is done every 6 hours if OpenCTI was able to connect to the hostname when the telemetry manager is started. Metrics are also written in specific logs files in order to be included in support package</p>"},{"location":"reference/usage-telemetry/#telemetry-metrics","title":"Telemetry metrics","text":"<p>The application collects statistical data related to its usage. Here are an exhaustive list of the collected metrics:</p> <ul> <li>The current platform version</li> <li>The platform unique identifier</li> <li>The platform creation date</li> <li>The number of active users</li> <li>The number of total users</li> <li>The number of nodes in the platform</li> <li>Enterprise Edition status (activated or not)</li> <li>The number of active connectors</li> </ul>"},{"location":"usage/ask-ai/","title":"Ask AI","text":"<p>Enterprise edition</p> <p>Ask AI is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"usage/ask-ai/#prerequisites-for-using-ask-ai","title":"Prerequisites for using Ask AI","text":"<p>There are several possibilities for Enterprise Edition customers to use OpenCTI AI endpoints:</p> <ul> <li>Use the Filigran AI Service leveraging our custom AI model using the token given by the support team.</li> <li>Use OpenAI or MistralAI cloud endpoints using your own tokens.</li> <li>Deploy or use local AI endpoints (Filigran can provide you with the custom model).</li> </ul> <p>Please read the configuration documentation</p> <p>Beta Feature</p> <p>Ask AI is a beta feature as we are currently fine-tuning our models. Consider checking important information.</p>"},{"location":"usage/ask-ai/#how-it-works","title":"How it works","text":"<p>Even if in the future, we would like to leverage AI to do RAG, for the moment we are mostly using AI to analyze and produce texts or images, based on data directly sent into the prompt.</p> <p>This means that if you are using Filigran AI endpoint or a local one, your data is never used to re-train or adapt the model and everything relies on a pre-trained and fixed model. When using the <code>Ask AI</code> button in the platform, a prompt is generated with the proper instruction to generate the expected result and use it in the context of the button (in forms, rich text editor etc.).</p>"},{"location":"usage/ask-ai/#filigran-custom-model","title":"Filigran custom model","text":"<p>We are hosting a scalable AI endpoint for all SaaS or On-Prem enterprise edition customers, this endpoint is based on MistralAI with a model that will be adapted over time to be more effective when processing threat intelligence related contents.</p> <p>The model, which is still in beta version, will be adapted in the upcoming months to reach maturity at the end of 2024. It can be shared with on-prem enterprise edition customers under NDA.</p>"},{"location":"usage/ask-ai/#functionalities-of-ask-ai","title":"Functionalities of Ask AI","text":"<p>Ask AI is represented by a dedicated icon wherever on of its functionalities is available to use.</p> <p></p>"},{"location":"usage/ask-ai/#assistance-for-writing-meaningful-content","title":"Assistance for writing meaningful content","text":"<p>Ask AI can assist you for writing better textual content, for example better title, name, description and detailed content of Objects.</p> <ul> <li>Fix spelling &amp; grammar: try to improve the text from a formulation and grammar perspective.  </li> <li>Make it shorter/longer: try to shorten or lengthen the text.</li> <li>Change tone: try to change the tone of the text. You can select if you want the text to be written for Strategic (Management, decision makers), Tactical (for team leaders) or Operational (for technical CTI analysts) audiences.</li> <li>Summarize: try to summarize the text in bullet points.</li> <li>Explain: try to explain the context of the subject's text based on what is available to the LLM.</li> </ul>"},{"location":"usage/ask-ai/#assistance-for-importing-data-from-documents","title":"Assistance for importing data from documents","text":"<p>Fom the Content tab of a Container (Reports, Groupings and Cases), Ask AI can also assist you for importing data contained in uploaded documents into OpenCTI for further exploitation.</p> <ul> <li>Generate report document: Generate a text report based on the knowledge graph (entities and relationships) of this container.</li> <li>Summarize associated files: Generate a summary of the selected files (or all files associated to this container).</li> <li>Try to convert the selected files (or all files associated to this container) in a STIX 2.1 bundle you will then be able to use at your convenience (for example importing it into the platform).</li> </ul> <p></p> <p></p> <p>A short video on the FiligranHQ YouTube channel presents tha capabilities of AskAI: https://www.youtube.com/watch?v=lsP3VVsk5ds.</p>"},{"location":"usage/ask-ai/#improving-generated-elements-of-ask-ai","title":"Improving generated elements of Ask AI","text":"<p>Be aware that the text quality is highly dependent on the capabilities of the associated LLM.</p> <p>That is why every generated text by Ask AI is provided in a dedicated panel, allowing you to verify and rectify any error the LLM could have made.</p>"},{"location":"usage/automation/","title":"Playbooks Automation","text":"<p>Enterprise edition</p> <p>Playbooks automation is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all information.</p> <p>OpenCTI playbooks are flexible automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform. </p> <p>Playbook automation is accessible in the user interface under Data &gt; Processing &gt; Automation.</p> <p>Right needed</p> <p>You need the \"Manage credentials\" capability to use the Playbooks automation, because you will be able to manipulate data simple users cannot access.</p> <p>You will then be able to:</p> <ul> <li>add labels depending on enrichment results to be used in threat intelligence-driven detection feeds,</li> <li>create reports and cases based on various criteria,</li> <li>trigger enrichments or webhooks in given conditions,</li> <li>modify attributes such as first_seen and last_seen based on other pieces of knowledge,</li> <li>etc.</li> </ul>"},{"location":"usage/automation/#playbook-philosophy","title":"Playbook philosophy","text":"<p>Consider Playbook as a STIX 2.1 bundle pipeline. </p> <p>Initiating with a component listening to a data stream, each subsequent component in the playbook processes a received STIX bundle. These components have the ability to modify the bundle and subsequently transmit the altered result to connected components.</p> <p>In this paradigm, components can send out the STIX 2.1 bundle to multiple components, enabling the development of multiple branches within your playbook.</p> <p>A well-designed playbook end with a component executing an action based on the processed information. For instance, this may involve writing the STIX 2.1 bundle in a data stream.</p> <p>Validate ingestion</p> <p>The STIX bundle processed by the playbook won't be written in the platform without specifying it using the appropriate component, i.e. \"Send for ingestion\".</p>"},{"location":"usage/automation/#create-a-playbook","title":"Create a Playbook","text":"<p>It is possible to create as many playbooks as needed which are running independently. You can give a name and description to each playbook.</p> <p></p> <p>The first step to define in the playbook is the \u201ctriggering event\u201d, which can be any knowledge event (create, update or delete) with customizable filters. To do so, click on the grey rectangle in the center of the workspace and choose the component to \"listen knowledge events\". Configure it with adequate filters. You can use same filters as in other part of the platform.</p> <p></p> <p>Then you have flexible choices for the next steps to:</p> <ul> <li>filter the initial knowledge,</li> <li>enrich data using external sources and internal rules,</li> <li>modify entities and relationships by applying patches,</li> <li>write the data, send notifications, </li> <li>etc.</li> </ul> <p>Do not forget to start your Playbook when ready, with the Start option of the burger button placed near the name of your Playbook.</p> <p>By clicking the burger button of a component, you can replace it by another one.</p> <p>By clicking on the arrow icon in the bottom right corner of a component, you can develop a new branch at the same level.</p> <p>By clicking the \"+\" button on a link between components, you can insert a component between the two.</p>"},{"location":"usage/automation/#components-of-playbooks","title":"Components of playbooks","text":""},{"location":"usage/automation/#log-data-in-standard-output","title":"Log data in standard output","text":"<p>Will write the received STIX 2.1 bundle in platform logs with configurable log level and then send out the STIX 2.1 bundle unmodified.</p>"},{"location":"usage/automation/#send-for-ingestion","title":"Send for ingestion","text":"<p>Will pass the STIX 2.1 bundle to be written in the data stream. This component has no output and should end a branch of your playbook.</p>"},{"location":"usage/automation/#filter-knowledge","title":"Filter Knowledge","text":"<p>Will allow you to define filter and apply it to the received STIX 2.1 bundle. The component has 2 output, one for data matching the filter and one for the remainder.</p> <p>By default, filtering is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#enrich-through-connector","title":"Enrich through connector","text":"<p>Will send the received STIX 2.1 bundle to a compatible enrichment connector and send out the modified bundle.</p>"},{"location":"usage/automation/#manipulate-knowledge","title":"Manipulate knowledge","text":"<p>Will add, replace or remove compatible attribute of the entities contains in the received STIX 2.1 bundle and send out the modified bundle.</p> <p>By default, modification is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#container-wrapper","title":"Container wrapper","text":"<p>Will modify the received STIX 2.1 bundle to include the entities into an container of the type you configured.  By default, wrapping is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#share-with-organizations","title":"Share with organizations","text":"<p>Will share every entity in the received STIX 2.1 bundle with Organizations you configured. Your platform need to have declared a platform main organization in Settings/Parameters.</p>"},{"location":"usage/automation/#apply-predefined-rule","title":"Apply predefined rule","text":"<p>Will apply a complex automation built-in rule. This kind of rule might impact performance. Current rules are:</p> <ul> <li>First/Last seen computing extension from report publication date: will populate first seen and last seen date of entities contained in the report based on its publication date,</li> <li>Resolve indicators based on observables (add in bundle): will retrieve all indicators linked to the bundle's observables from the database,</li> <li>Resolve observables an indicator is based on (add in bundle): retrieve all observables linked to the bundle's indicator from the database,</li> <li>Resolve container references (add in bundle): will add to the bundle all the relationships and entities the container contains (if the entity having triggered the playbook is not a container, the output of this component will be empty),</li> <li>Resolve neighbors relations and entities (add in bundle): will add to the bundle all relations of the entity having triggered the playbook, as well as all entities at the end of these relations, i.e. the \"first neighbors\" (if the entity is a container, the output of this component will be empty).</li> </ul>"},{"location":"usage/automation/#send-to-notifier","title":"Send to notifier","text":"<p>Will generate a Notification each time a STIX 2.1 bundle is received.</p>"},{"location":"usage/automation/#promote-observable-to-indicator","title":"Promote observable to indicator","text":"<p>Will generate indicator based on observables contained in the received STIX 2.1 bundle. </p> <p>By default, it is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all observables in the bundle (e.g. observables that might result from predefined rule).</p> <p>You can also add all indicators and relationships generated by this component in the entity having triggered the playbook, if this entity is a container.</p>"},{"location":"usage/automation/#extract-observables-from-indicator","title":"Extract observables from indicator","text":"<p>Will extract observables based on indicators contained in the received STIX 2.1 bundle. </p> <p>By default, it is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all indicators in the bundle (e.g. indicators that might result from enrichment.</p> <p>You can also add all observables and relationships generated by this component in the entity having triggered the playbook, if this entity is a container.</p>"},{"location":"usage/automation/#reduce-knowledge","title":"Reduce Knowledge","text":"<p>Will elagate the received STIX 2.1 bundle based on the configured filter.</p>"},{"location":"usage/automation/#monitor-playbook-activity","title":"Monitor playbook activity","text":"<p>At the top right of the interface, you can access execution trace of your playbook and consult the raw data after every step of your playbook execution.</p> <p></p>"},{"location":"usage/background-tasks/","title":"Background tasks","text":"<p>Three types of tasks are done in the background:</p> <ul> <li>rule tasks,</li> <li>knowledge tasks,</li> <li>user tasks.</li> </ul> <p>Rule tasks can be seen and activated in Settings &gt; Customization &gt; Rules engine. Knowledge and user tasks can be seen and managed in Data &gt; Background Tasks. The scope of each task is indicated.</p> <p></p>"},{"location":"usage/background-tasks/#rule-tasks","title":"Rule tasks","text":"<p>If a rule task is enabled, it leads to the scan of the whole platform data and the creation of entities or relationships in case a configuration corresponds to the tasks rules. The created data are called 'inferred data'. Each time an event occurs in the platform, the rule engine checks if inferred data should be updated/created/deleted.</p>"},{"location":"usage/background-tasks/#knowledge-tasks","title":"Knowledge tasks","text":"<p>Knowledge tasks are background tasks updating or deleting entities and correspond to mass operations on these data. To create one, select entities via the checkboxes in an entity list, and choose the action to perform via the toolbar.</p>"},{"location":"usage/background-tasks/#rights","title":"Rights","text":"<ul> <li>To create a knowledge task, the user should have the capability to Update Knowledge (or the capability to delete knowledge if the task action is a deletion).</li> <li>To see a knowledge task in the Background task section, the user should be the creator of the task, or have the KNOWLEDGE capability.</li> <li>To delete a knowledge task from the Background task section, the user should be the creator of the task, or have the KNOWLEDGE_UPDATE capability.</li> </ul>"},{"location":"usage/background-tasks/#user-tasks","title":"User tasks","text":"<p>User tasks are background tasks updating or deleting notifications. It can be done from the Notification section, by selecting several notifications via the checkboxes, and choosing an action via the toolbar.</p>"},{"location":"usage/background-tasks/#rights_1","title":"Rights","text":"<ul> <li>A user can create a user task on its own notifications only.</li> <li>To see or delete a user task, the user should be the creator of the task or have the SET_ACCESS capability.</li> </ul>"},{"location":"usage/case-management/","title":"Case management","text":""},{"location":"usage/case-management/#why-case-management","title":"Why Case management?","text":"<p>Compiling CTI data in one place, deduplicate and correlate to transform it into Intelligence is very important. But ultimately, you need to act based on this Intelligence. Some situations will need to be taken care of, like cybersecurity incidents, requests for information or requests for takedown. Some actions will then need to be traced, to be coordinated and oversaw. Some actions will include feedback and content delivery.</p> <p>OpenCTI includes Cases to allow organizations to manage situations and organize their team's work. Better, by doing Case management in OpenCTI, you handle your cases with all the context and Intelligence you need, at hand.</p>"},{"location":"usage/case-management/#how-to-manage-your-case-in-opencti","title":"How to manage your Case in OpenCTI?","text":"<p>Multiple situations can be modelize in OpenCTI as a Case, either an Incident Response, a Request for Takedown or a Request for Information.</p> <p></p> <p>All Cases can contain any entities and relationships you need to represent the Intelligence context related to the situation. At the beginning of your case, you may find yourself with only some Observables sighted in a system. At the end, you may have Indicators, Threat Actor, impacted systems, attack patterns. All representing your findings, ready to be presented and exported as graph, pdf report, timeline, etc.</p> <p></p> <p>Some Cases may need some collaborative work and specific Tasks to be performed by people that have the skillset for. OpenCTI allows you to associate <code>Tasks</code> in your Cases and assign them to users in the platform. As some type of situation may need the same tasks to be done, it is also possible to pre-define lists of tasks to be applied on your case. You can define these lists by accessing the Settings/Taxonomies/Case templates panel. Then you just need to add it from the overview of your desire Case.</p> <p>Tip: A user can have a custom dashboard showing him all the tasks that have been assigned to him.</p> <p></p> <p>As with other objects in OpenCTI, you can also leverage the <code>Notes</code> to add some investigation and analysis related comments, helping you shaping up the content of your case with unstructured data and trace all the work that have been done.</p> <p>You can also use <code>Opinions</code> to collect how the Case has been handled, helping you to build Lessons Learned.</p> <p></p> <p>To trace the evolution of your Case and define specific resolution worflows, you can use the <code>Status</code> (that can be define in Settings/Taxonomies/Status templates).</p> <p>At the end of your Case, you will certainly want to report on what have been done. OpenCTI allows you to export the content of the Case in a simple but customizable PDF (currently in refactor). But of course, your company have its own documents' templates, right? With OpenCTI, you will be able to include some nice graphics in it. For example, a Matrix view of the attacker attack pattern or even a graph display of how things are connected. </p> <p>Also, we are currently working a more meaningfull Timeline view that will be possible to export too.</p>"},{"location":"usage/case-management/#use-case-example-a-suspicious-observable-is-sighted-by-a-defense-system-is-it-important","title":"Use case example: A suspicious observable is sighted by a defense system. Is it important?","text":"<ul> <li>Daily, your SIEM and EDR are feeded Indicators of Compromise from your OpenCTI instance. </li> <li>Today, your SIEM have sighted the domain name \"bad.com\" matching one of them. Its alert has been transfered to OpenCTI and have created a <code>Sighting</code> relationship between your System \"SIEM permiter A\" and the Observable \"bad.com\". </li> <li>You are alerted immediatly, because you have activated the inference rule creating a corresponding <code>Incident</code> in this situation, and you have created an alert based on new Incident that send you email <code>notification</code> and Teams message (webhook).</li> <li>In OpenCTI, you can clearly see the link between the alerting System, the sighted Observable and the corresponding Indicator. Better, you can also see all the context of the Indicator. It is linked to a notorious and recent phishing <code>campaign</code> targeting your activity <code>sector</code>. \"bad.com\" is clearly something to investigate ASAP.</li> <li>You quickly select all the context you have found, and add it to a new <code>Incident response</code>case. You position the priority to High, regarding the context, and the severity to Low, as you don't know yet if someone really interact with \"bad.com\"</li> <li>You also assign the case to one of your collegue, on duty for investigative work. To guide him, you also create a <code>Task</code> in your case for verifying if an actual interaction happened with \"bad.com\".</li> </ul>"},{"location":"usage/containers/","title":"Containers","text":""},{"location":"usage/containers/#stix-standard","title":"STIX standard","text":""},{"location":"usage/containers/#definition","title":"Definition","text":"<p>In the STIX 2.1 standard, some STIX Domain Objects (SDO) can be considered as \"container of knowledge\", using the <code>object_refs</code> attribute to refer multiple other objects as nested references. In <code>object_refs</code>, it is possible to refer to entities and relationships. </p>"},{"location":"usage/containers/#example","title":"Example","text":"<pre><code>{\n   \"type\": \"report\",\n   \"spec_version\": \"2.1\",\n   \"id\": \"report--84e4d88f-44ea-4bcd-bbf3-b2c1c320bcb3\",\n   \"created_by_ref\": \"identity--a463ffb3-1bd9-4d94-b02d-74e4f1658283\",\n   \"created\": \"2015-12-21T19:59:11.000Z\",\n   \"modified\": \"2015-12-21T19:59:11.000Z\",\n   \"name\": \"The Black Vine Cyberespionage Group\",\n   \"description\": \"A simple report with an indicator and campaign\",\n   \"published\": \"2016-01-20T17:00:00.000Z\",\n   \"report_types\": [\"campaign\"],\n   \"object_refs\": [\n      \"indicator--26ffb872-1dd9-446e-b6f5-d58527e5b5d2\",\n      \"campaign--83422c77-904c-4dc1-aff5-5c38f3a2c55c\",\n      \"relationship--f82356ae-fe6c-437c-9c24-6b64314ae68a\"\n   ]\n}\n</code></pre> <p>In the previous example, we have a nested reference to 3 other objects:</p> <pre><code>\"object_refs\": [\n   \"indicator--26ffb872-1dd9-446e-b6f5-d58527e5b5d2\",\n   \"campaign--83422c77-904c-4dc1-aff5-5c38f3a2c55c\",\n   \"relationship--f82356ae-fe6c-437c-9c24-6b64314ae68a\"\n]\n</code></pre>"},{"location":"usage/containers/#implementation","title":"Implementation","text":""},{"location":"usage/containers/#types-of-container","title":"Types of container","text":"<p>In OpenCTI, containers are displayed differently than other entities, because they contain pieces of knowledge. Here is the list of containers in the platform:</p> Type of entity STIX standard Description Report Native Reports are collections of threat intelligence focused on one or more topics, such as a description of a threat actor, malware, or attack technique, including context and related details. Grouping Native A Grouping object explicitly asserts that the referenced STIX Objects have a shared context, unlike a STIX Bundle (which explicitly conveys no context). Observed Data Native Observed Data conveys information about cyber security related entities such as files, systems, and networks using the STIX Cyber-observable Objects (SCOs). Note Native A Note is intended to convey informative text to provide further context and/or to provide additional analysis not contained in the STIX Objects. Opinion Native An Opinion is an assessment of the correctness of the information in a STIX Object produced by a different entity. Case Extension A case whether an Incident Response, a Request for Information or a Request for Takedown is used to convey an epic with a set of tasks. Task Extension A task, generally used in the context of a case, is intended to convey information about something that must be done in a limited timeframe."},{"location":"usage/containers/#containers-behavior","title":"Containers behavior","text":"<p>In the platform, it is always possible to visualize the list of entities and/or observables referenced in a container (<code>Container &gt; Entities or Observables</code>) but also to add / remove entities from the container.</p> <p></p> <p>As containers can also contain relationships, which are generally linked to the other entities in the container, it is also possible to visualize the container as a graph (<code>Container &gt; Knowledge</code>)</p> <p></p>"},{"location":"usage/containers/#containers-of-an-entity-or-a-relationship","title":"Containers of an entity or a relationship","text":"<p>On the entity or the relationship side, you can always find all containers where the object is contained using the top menu <code>Analysis</code>:</p> <p></p> <p>In all containers list, you can also filter containers based on one or multiple contained object(s):</p> <p></p>"},{"location":"usage/dashboards-share/","title":"Share custom dashboards","text":"<p>OpenCTI provides a simple way to share a visualisation of a custom dashboard to anyone, even for people that are outside of the platform. We call those visualisations: public dashboards.</p> <p>Public dashboards are a snapshot of a custom dashboard at a specific moment of time.  By this way you can share a version of a custom dashboard, then modify your custom dashboard without worrying about the impact on public dashboards you have created.</p> <p>On the contrary, if you want that your public dashboard is updated with the last version of the associated custom dashboard, you can do it with few clicks by recreating a public dashboard using the same name of the one to update.</p> <p>To be able to share custom dashboards you need to have the Manage data sharing &amp; ingestion capability.</p>"},{"location":"usage/dashboards-share/#create-a-public-dashboard","title":"Create a public dashboard","text":"<p>On the top-right of your custom dashboard page you will find a button that will open a panel to manage the public dashboards associated to this custom dashboard.</p> <p></p> <p>In this panel you will find two parts: - At the top you have a form allowing you to create public dashboards, - And below, the list of the public dashboards you have created.</p> <p></p>"},{"location":"usage/dashboards-share/#form-to-create-a-new-public-dashboard","title":"Form to create a new public dashboard","text":"<p>First you need to specify a name for your public dashboard. This name will be displayed on the dashboard page. The name is also used to generate an ID for your public dashboard that will be used in the URL to access the dashboard.</p> <p>The ID is generated as follow: replace all spaces with symbol <code>-</code> and remove special characters. This ID also needs to be unique in the platform as it is used in the URL to access the dashboard.</p> <p></p> <p>Then you can choose if the public dashboard is enabled or not. A disabled dashboard means that you cannot access the public dashboard through the custom URL. But you can still manage it from this panel.</p> <p></p> <p>Finally you choose the max level of marking definitions for the data to be displayed in the public dashboard. For example if you choose <code>TLP:AMBER</code> then the data fetched by the widgets inside the public dashboard will be at maximum AMBER, you won't retrieved data with RED marking definition.</p> <p>Also note that the list of marking definitions you can see is based on your current marking access on the platform and the maximum sharable marking definitions defined by the admin of the platform:</p> <p>As a platform administrator, you can define, for each type of marking definition, Maximum marking definitions shareable to be  shared through Public Dashboard, regardless of the definition set by users in their public dashboard.  This configuration is accessible in <code>settings &gt; security &gt; policies</code> (this step is mandatory for creating public  dashboards to ensure control over data sharing).</p> <p></p>"},{"location":"usage/dashboards-share/#list-of-the-public-dashboards","title":"List of the public dashboards","text":"<p>When you have created a public dashboard, it will appear in the list below the form.</p> <p></p> <p>In this list each item represents a public dashboard you have created. For each you can see its name, path of the URL, max marking definitions, the date of creation, the status to know if the dashboard is enabled or not and some actions.</p> <p>The possible actions are: copy the link of the public dashboard, disable or enable the dashboard and delete the dashboard.</p> <p>To share a public dashboard just copy the link and give the URL to the person you want to share with. The dashboard will be visible even if the person is not connected to OpenCTI.</p>"},{"location":"usage/dashboards/","title":"Custom dashboards","text":"<p>OpenCTI provides an adaptable and entirely customizable dashboard functionality. The flexibility of OpenCTI's dashboard ensures a tailored and insightful visualization of data, fostering a comprehensive understanding of the platform's knowledge, relationships, and activities.</p>"},{"location":"usage/dashboards/#dashboard-overview","title":"Dashboard overview","text":"<p>You have the flexibility to tailor the arrangement of widgets on your dashboard, optimizing organization and workflow efficiency. Widgets can be intuitively placed to highlight key information. Additionally, you can resize widgets from the bottom right corner based on the importance of the information, enabling adaptation to specific analytical needs. This technical flexibility ensures a fluid, visually optimized user experience.</p> <p>Moreover, the top banner of the dashboard offers a convenient feature to configure the timeframe for displayed data. This can be accomplished through the selection of a relative time period, such as \"Last 7 days\", or by specifying fixed \"Start\" and \"End\" dates, allowing users to precisely control the temporal scope of the displayed information.</p> <p></p> <p></p>"},{"location":"usage/dashboards/#access-control","title":"Access control","text":"<p>In OpenCTI, the power to create custom dashboards comes with a flexible access control system, allowing users to tailor visibility and rights according to their collaborative needs.</p> <p>When a user crafts a personalized dashboard, by default, it remains visible only to the dashboard creator. At this stage, the creator holds administrative access rights. However, they can extend access and rights to others using the \"Manage access\" button, denoted by a locker icon, located at the top right of the dashboard page.</p> <p></p> <p>Levels of access:</p> <ul> <li>View: Access to view the dashboard. </li> <li>Edit: View + Permission to modify and update the dashboard and its widgets. </li> <li>Manage: Edit + Ability to delete the dashboard and to control user access and rights.</li> </ul> <p>It's crucial to emphasize that at least one user must retain admin access to ensure ongoing management capabilities for the dashboard.</p> <p> </p> <p>Knowledge access restriction</p> <p>The platform's data access restrictions also apply to dashboards. The data displayed in the widgets is subject to the user's access rights within the platform. Therefore, an admin user will not see the same results in the widgets as a user with limited access, such as viewing only TLP:CLEAR data (assuming the platform contains data beyond TLP:CLEAR). </p>"},{"location":"usage/dashboards/#share-dashboard-and-widget-configurations","title":"Share dashboard and widget configurations","text":"<p>OpenCTI provides functionality for exporting, importing and duplicating dashboard and widget configurations, facilitating the seamless transfer of customized dashboard setups between instances or users.</p>"},{"location":"usage/dashboards/#export","title":"Export","text":"<p>Dashboards can be exported from either the custom dashboards list or the dashboard view. </p> <p>To export a dashboard configuration from the custom dashboards list:</p> <ol> <li>Click on the burger menu button at the end of the dashboard line.</li> <li>Select <code>Export</code>.</li> </ol> <p></p> <p>To export a widget, the same mechanism is used, but from the burger menu button in the upper right-hand corner of the widget.</p> <p></p> <p>To export a dashboard configuration from the dashboard view:</p> <ol> <li>Navigate to the desired dashboard.</li> <li>Click on the <code>Export</code> button (file with an arrow pointing to the top right corner) located in the top-right corner of the dashboard.</li> </ol> <p></p>"},{"location":"usage/dashboards/#configuration-file","title":"Configuration file","text":"<p>The dashboard configuration will be saved as a JSON file, with the title formatted as <code>[YYYYMMDD]_octi_dashboard_[dashboard title]</code>. The expected configuration file content is as follows:</p> <pre><code>{\n  \"openCTI_version\": \"5.12.0\",\n  \"type\": \"dashboard\",\n  \"configuration\": {\n    \"name\": \"My dashboard title\",\n    \"manifest\": \"eyJ3aWRn(...)uZmlnIjp7fX0=\"\n  }\n}\n</code></pre> <p>The widget configuration will be saved as a JSON file, with the title formatted as <code>[YYYYMMDD]_octi_widget_[widget view]</code>. The expected configuration file content is as follows:</p> <pre><code>{\n  \"openCTI_version\": \"5.12.0\",\n  \"type\": \"widget\",\n  \"configuration\": \"eyJ0eXB(...)iOmZhbHNlfX0=\"\n}\n</code></pre> <p>Source platform-related filters</p> <p>When exporting a dashboard or widget configuration, all filters will be exported as is. Filters on objects that do not exist in the receiving platform will need manual deletion after import. Filters to be deleted can be identified by their \"delete\" barred value.</p> <p></p>"},{"location":"usage/dashboards/#import","title":"Import","text":"<p>Dashboards can be imported from the custom dashboards list:</p> <ol> <li>Hover over the Add button (+) in the right bottom corner.</li> <li>Click on the <code>Import dashboard</code> button (cloud with an upward arrow).</li> <li>Select your file.</li> </ol> <p></p> <p>To import a widget, the same mechanism is used, but from a dashboard view.</p> <p></p> <p>Configuration compatibility</p> <p>Only JSON files with the required properties will be accepted, including \"openCTI_version: [5.12.0 and above]\", \"type: [dashboard|widget]\", and a \"configuration\". This applies to both dashboards and widgets configurations.</p>"},{"location":"usage/dashboards/#duplicate","title":"Duplicate","text":"<p>Dashboards can be duplicated from either the custom dashboards list or the dashboard view.</p> <p>To duplicate a dashboard from the custom dashboards list:</p> <ol> <li>Click on the burger menu button at the end of the dashboard line.</li> <li>Select <code>Duplicate</code>.</li> </ol> <p>To duplicate a widget, the same mechanism is used, but from the burger menu button in the upper right-hand corner of the widget.</p> <p>To duplicate a dashboard from the dashboard view:</p> <ol> <li>Navigate to the desired dashboard.</li> <li>Click on the <code>Duplicate the dashboard</code> button (two stacked sheets) located in the top-right corner of the dashboard.</li> </ol> <p></p> <p>Upon successful duplication, a confirmation message is displayed for a short duration, accompanied by a link for easy access to the new dashboard view. Nevertheless, the new dashboard can still be found in the dashboards list.</p> <p></p> <p>Dashboard access</p> <p>The user importing or duplicating a dashboard becomes the only one with access to it. Then, access can be managed as usual.</p>"},{"location":"usage/data-model/","title":"Data model","text":""},{"location":"usage/data-model/#introduction","title":"Introduction","text":"<p>The OpenCTI core design relies on the concept of a knowledge graph, where you have two different kinds of object:</p> <ol> <li>Nodes are used to describe <code>entities</code>, which have some <code>properties</code> or <code>attributes</code>.</li> <li>Edges are used to describe <code>relationships</code>, which are created between two <code>entity</code> nodes and have some <code>properties</code> or <code>attributes</code>.</li> </ol> <p>Example</p> <p>An example would be that the entity <code>APT28</code> has a relationship <code>uses</code> to the malware entity <code>Drovorub</code>.</p>"},{"location":"usage/data-model/#standard","title":"Standard","text":""},{"location":"usage/data-model/#the-stix-model","title":"The STIX model","text":"<p>To enable a unified approach in the description of threat intelligence knowledge as well as importing and exporting data, the OpenCTI data model is based on the STIX 2.1 standard. Thus we highly recommend to take a look to the STIX Introductory Walkthrough and to the different kinds of STIX relationships to get a better understanding of how OpenCTI works.</p> <p>Some more important STIX naming shortcuts are:</p> <ul> <li>STIX Domain Objects (SDO): Attack Patterns, Malware, Threat Actors, etc.</li> <li>STIX Cyber Observable (SCO): IP Addresses, domain names, hashes, etc.</li> <li>STIX Relationship Object (SRO): Relationships, Sightings</li> </ul> <p></p>"},{"location":"usage/data-model/#extensions","title":"Extensions","text":"<p>In some cases, the model has been extended to be able to:</p> <ul> <li>Support more types of SCOs to modelize information systems such as cryptocurrency wallets, user agents, etc.</li> <li>Support more types of SDOs to modelize disinformation and cybercrime such as channels, events, narrative, etc.</li> <li>Support more types of SROs to extend the new SDOs such as<code>amplifies</code>, <code>publishes</code>, etc.</li> </ul>"},{"location":"usage/data-model/#implementation-in-the-platform","title":"Implementation in the platform","text":""},{"location":"usage/data-model/#diagram-of-types","title":"Diagram of types","text":"<p>You can find below the digram of all types of entities and relationships available in OpenCTI.</p>"},{"location":"usage/data-model/#attributes-and-properties","title":"Attributes and properties","text":"<p>To get a comprehensive list of available properties for a given type of entity or relationship, you can use the GraphQL playground schema available in your \"Profile &gt; Playground\". Then you can click on schema. You can for instance search for the keyword <code>IntrusionSet</code>:</p> <p></p>"},{"location":"usage/dates/","title":"Meaning of dates","text":"<p>In OpenCTI, entities can contain various dates, each representing different types of information. The available dates vary depending on the entity types.</p>"},{"location":"usage/dates/#dates","title":"Dates","text":"<p>In OpenCTI, dates play a crucial role in understanding the context and history of entities. Here's a breakdown of the different dates you might encounter in the platform:</p> <ul> <li>\u201cPlatform creation date\u201d: This date signifies the moment the entity was created within OpenCTI. On the API side, this timestamp corresponds to the <code>created_at</code> field. It reflects the initiation of the entity within the OpenCTI environment.</li> <li>\u201cOriginal creation date\u201d: This date reflects the original creation date of the data on the source's side. It becomes relevant if the source provides this information and if the connector responsible for importing the data takes it into account. In cases where the source date is unavailable or not considered, this date defaults to the import date (i.e. the \u201cPlatform creation date\u201d). On the API side, this timestamp corresponds to the <code>created</code> field.</li> <li>\u201cModification date\u201d: This date captures the most recent modification made to the entity, whether a connector automatically modifies it or a user manually edits the entity. On the API side, this timestamp corresponds to the <code>updated_at</code> field. It serves as a reference point for tracking the latest changes made to the entity.</li> <li>Date not shown on GUI: There is an additional date which is not visible on the entity in the GUI. This date is the <code>modified</code> field on the API. This date reflects the original update date of the data on the source's side. The difference between <code>modified</code> and <code>updated_at</code> is identical to the difference between <code>created</code> and <code>created_at</code>.</li> </ul> <p></p> <p>Understanding these dates is pivotal for contextualizing the information within OpenCTI, ensuring a comprehensive view of entity history and evolution.</p>"},{"location":"usage/dates/#date-types","title":"Date types","text":""},{"location":"usage/dates/#technical-dates","title":"Technical dates","text":"<p>The technical dates refer to the dates directly associated to data management within the platform. The API fields corresponding to technical dates are:</p> <ul> <li>created_at: Indicates the date and time when the entity was created in the platform.</li> <li>updated_at: Represents the date and time of the most recent update to the entity in the platform.</li> </ul>"},{"location":"usage/dates/#functional-dates","title":"Functional dates","text":"<p>The functional dates are the dates functionally significant, often indicating specific events or milestones. The API fields corresponding to functional dates are:</p> <ul> <li>created: Denotes the date and time when the entity was created on the source's side.</li> <li>modified: Represents the date and time of the most recent modification to the entity on the source's side.</li> <li>start_time: Indicates the start date and time associated with a relationship.</li> <li>stop_time: Indicates the stop date and time associated with a relationship.</li> <li>first_seen: Represents the initial date and time when the entity/activity was observed.</li> <li>last_seen: Represents the most recent date and time when the entity/activity was observed.</li> </ul>"},{"location":"usage/deduplication/","title":"Deduplication","text":"<p>One of the core concept of the OpenCTI knowledge graph is all underlying mechanisms implemented to accurately de-duplicate and consolidate (aka. <code>upserting</code>) information about entities and relationships.</p>"},{"location":"usage/deduplication/#creation-behavior","title":"Creation behavior","text":"<p>When an object is created in the platform, whether manually by a user or automatically by the connectors / workers chain, the platform checks if something already exist based on some properties of the object. If the object already exists, it will return the existing object and, in some cases, update it as well.</p> <p>Technically, OpenCTI generates deterministic IDs based on the listed properties below to prevent duplicate (aka \"ID Contributing Properties\"). Also, it is important to note that there is a special link between <code>name</code> and <code>aliases</code> leading to not have entities with overlapping aliases or an alias already used in the name of another entity.</p>"},{"location":"usage/deduplication/#entities","title":"Entities","text":"Type Attributes Area (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Attack Pattern (<code>name</code> OR <code>alias</code>) AND optional <code>x_mitre_id</code> Campaign <code>name</code> OR <code>alias</code> Channel <code>name</code> OR <code>alias</code> City (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Country (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Course Of Action (<code>name</code> OR <code>alias</code>) AND optional <code>x_mitre_id</code> Data Component <code>name</code> OR <code>alias</code> Data Source <code>name</code> OR <code>alias</code> Event <code>name</code> OR <code>alias</code> Feedback Case <code>name</code> AND <code>created</code> (date) Grouping <code>name</code> AND <code>context</code> Incident <code>name</code> OR <code>alias</code> Incident Response Case <code>name</code> OR <code>alias</code> Indicator <code>pattern</code> OR <code>alias</code> Individual (<code>name</code> OR <code>x_opencti_alias</code>) and <code>identity_class</code> Infrastructure <code>name</code> OR <code>alias</code> Intrusion Set <code>name</code> OR <code>alias</code> Language <code>name</code> OR <code>alias</code> Malware <code>name</code> OR <code>alias</code> Malware Analysis <code>name</code> OR <code>alias</code> Narrative <code>name</code> OR <code>alias</code> Note None Observed Data <code>name</code> OR <code>alias</code> Opinion None Organization (<code>name</code> OR <code>x_opencti_alias</code>) and <code>identity_class</code> Position (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Region <code>name</code> OR <code>alias</code> Report <code>name</code> AND <code>published</code> (date) RFI Case <code>name</code> AND <code>created</code> (date) RFT Case <code>name</code> AND <code>created</code> (date) Sector (<code>name</code> OR <code>alias</code>) and <code>identity_class</code> Task None Threat Actor <code>name</code> OR <code>alias</code> Tool <code>name</code> OR <code>alias</code> Vulnerability <code>name</code> OR <code>alias</code> <p>Names and aliases management</p> <p>The name and aliases of an entity define a set of unique values, so it's not possible to have the name equal to an alias and vice versa.</p>"},{"location":"usage/deduplication/#relationships","title":"Relationships","text":"<p>The deduplication process of relationships is based on the following criterias:</p> <ul> <li>Type</li> <li>Source</li> <li>Target</li> <li>Start time between -30 days / + 30 days</li> <li>Stop time between -30 days / + 30 days</li> </ul>"},{"location":"usage/deduplication/#observables","title":"Observables","text":"<p>For STIX Cyber Observables, OpenCTI also generate deterministic IDs based on the STIX specification using the \"ID Contributing Properties\" defined for each type of observable.</p>"},{"location":"usage/deduplication/#update-behavior","title":"Update behavior","text":"<p>In cases where an entity already exists in the platform, incoming creations can trigger updates to the existing entity's attributes. This logic has been implemented to converge the knowledge base towards the highest confidence and quality levels for both entities and relationships.</p> <p>To understand in details how the deduplication mechanism works in context of the maximum confidence level, you can navigate through this diagram (section deduplication):</p>"},{"location":"usage/delete-restore/","title":"Delete and restore knowledge","text":"<p>Knowledge can be deleted from OpenCTI either in an overview of an object or using background tasks When an object is deleted, all its relationships and references to other objects are also deleted. </p> <p>The deletion event is written to the stream, to trigger automated playbooks or synchronize another platform.</p> <p>Since OpenCTI 6.1, a record of the deleted objects is kept for a given period of a time, allowing to restore them on demand. This does not impact the stream events or other side effect of the deletion: the object is still deleted.</p>"},{"location":"usage/delete-restore/#trash","title":"Trash","text":"<p>A view called \"Trash\" displays all \"delete\" operations, entities and relationships alike.</p> <p></p> <p>A delete operation contains not only the entity or relationship that has been deleted, but also all the relationships and references from (to) this main object to (from) other elements in the platform.</p> <p>You can sort, filter or search this table using the usual UI controls. You are limited to the type of object, their representation (most of the time, the name of the object), the user who deleted the object, the date and time of deletion and the marking of the object.</p> <p>Note that the delete operations (i.e. the entries in this table view) inherit the marking of the main entity that was deleted, and thus follow the same access restriction as the object that was deleted.</p> <p>You can individually restore or permanently delete an object from the trash view using the burger menu at the end of the line.</p> <p></p> <p>Alternatively, you can use the checkboxes at the start of the line to select a subset of deleted objects, and trigger a background task to restore or permanently delete them by batch.</p>"},{"location":"usage/delete-restore/#restore","title":"Restore","text":"<p>Restoring an element creates it again in the platform with the same information it had before its deletion. It also restores all the relationships from or to this object, that have been also deleted during the deletion operation. If the object had attached files (uploaded or exported), they are also restored.</p> <p></p>"},{"location":"usage/delete-restore/#permanent-delete","title":"Permanent delete","text":"<p>From the Trash panel, it is also possible to delete permanently the object, its relationships, and attached files.</p> <p></p>"},{"location":"usage/delete-restore/#trash-retention","title":"Trash retention","text":"<p>Deleted objects are kept in trash during a fixed period of time (7 days by default), then they are permanently deleted by the trash manager.</p>"},{"location":"usage/delete-restore/#limitations","title":"Limitations","text":"<p>When it comes to restoring a deleted object from the trash, the current implementation shows several limitations.  First and foremost, if an object in the trash has lost a relationship dependency (i.e. the other side of a relationship from or to this object is no longer in live database), you will not be able to restore the object.</p> <p></p> <p>In such case, if the missing dependency is in the trash too, you can manually restore this dependency first and then retry.</p> <p>If the missing dependency has been permanently deleted, the object cannot be recovered.</p> <p></p> <p>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</p>"},{"location":"usage/enrichment/","title":"Enrichment connectors","text":"<p>Enriching the data within the OpenCTI platform is made seamlessly through the integration of enrichment connectors. These connectors facilitate the retrieval of additional data from external sources or portals.</p>"},{"location":"usage/enrichment/#automatic-enrichment","title":"Automatic enrichment","text":"<p>Enrichment can be conducted automatically in two distinct modes:</p> <ul> <li>Upon data arrival: Configuring the connector to run automatically when data arrives in OpenCTI ensures a real-time enrichment process, supplementing the platform's data. However, it's advisable to avoid automatic enrichment for quota-based connectors to paid sources to prevent quickly depleting all quotas. Additionally, this automatic enrichment contributes to increased data volume. On a large scale, with hundreds of thousands of objects, the disk space occupied by this data can be substantial, and it should be considered, especially if disk space is a concern. The automatic execution is configured at the connector level using the \"auto: true|false\" parameter.</li> <li>Targeted enrichment via playbooks: Enrichment can also be performed in a more targeted manner using playbooks. This approach allows for a customized enrichment strategy, focusing on specific objects and optimizing the relevance of the retrieved data.</li> </ul>"},{"location":"usage/enrichment/#manual-enrichment","title":"Manual enrichment","text":"<p>Manually initiating the enrichment process is straightforward. Simply locate the button with the cloud icon at the top right of an entity. </p> <p></p> <p>Clicking on this icon unveils a side panel displaying a list of available connectors that can be activated for the given object. If no connectors appear in the panel, it indicates that no enrichment connectors are available for the specific type of object in focus.</p> <p></p> <p>Activation of an enrichment connector triggers a contact with the designated remote source, importing a set of data into OpenCTI to enrich the selected object. Each enrichment connector operates uniquely, focusing on a specific set of object types it can enrich and a distinct set of data it imports. Depending on the connectors, they may, establish relationships, add external references, or complete object information, thereby contributing to the comprehensiveness of information within the platform.</p> <p>The list of available connectors can be found in our connectors catalog. In addition, further documentation on connectors is available on the dedicated documentation page.</p> <p>Impact of the max confidence level</p> <p>The maximum confidence level per user can have an impact on enrichment connectors, not being able to update data in the platform. To understand the concept and the potential issues you could face, please navigate to this page to understand.</p>"},{"location":"usage/exploring-analysis/","title":"Analyses","text":"<p>When you click on \"Analyses\" in the left-side bar, you see all the \"Analyses\" tabs, visible on the top bar on the left. By default, the user directly access the \"Reports\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Analyses</code> section, users can access the following tabs:</p> <ul> <li><code>Reports</code>: See Reports as a sort of containers to detail and structure what is contained on a specific report, either from a source or write by yourself. Think of it as an Intelligence Production in OpenCTI.</li> <li><code>Groupings</code>: Groupings are containers, like Reports, but do not represent an Intelligence Production. They regroup Objects sharing an explicit context. For example, a Grouping might represent a set of data that, in time, given sufficient analysis, would mature to convey an incident or threat report as Report container.</li> <li><code>Malware Analyses</code>: As define by STIX 2.1 standard, Malware Analyses captures the metadata and results of a particular static or dynamic analysis performed on a malware instance or family.</li> <li><code>Notes</code>: Through this tab, you can find all the Notes that have been written in the platform, for example to add some analyst's unstructured knowledge about an Object.</li> <li><code>External references</code>: Intelligence is never created from nothing. External references give user a way to link sources or reference documents to any Object in the platform.</li> </ul> <p></p>"},{"location":"usage/exploring-analysis/#reports","title":"Reports","text":""},{"location":"usage/exploring-analysis/#general-presentation","title":"General presentation","text":"<p>Reports are one of the central component of the platform. It is from a <code>Report</code> that knowledge is extracted and integrated in the platform for further navigation, analyses and exports. Always tying the information back to a report allows for the user to be able to identify the source of any piece of information in the platform at all time.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Report</code> is defined as such :</p> <p>Reports are collections of threat intelligence focused on one or more topics, such as a description of a threat actor, malware, or attack technique, including context and related details. They are used to group related threat intelligence together so that it can be published as a comprehensive cyber threat story.</p> <p>As a result, a <code>Report</code> object in OpenCTI is a set of attributes and metadata defining and describing a document outside the platform, which can be a threat intelligence report from a security reseearch team, a blog post, a press article a video, a conference extract, a MISP event, or any type of document and source.</p> <p>When clicking on the Reports tab at the top left, you see the list of all the Reports you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of reports.</p>"},{"location":"usage/exploring-analysis/#visualizing-knowledge-within-a-report","title":"Visualizing Knowledge within a Report","text":"<p>When clicking on a Report, you land on the Overview tab. For a Report, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge contained in the report, accessible through different views (See below for a dive-in). As described here.</li> <li>Content: a tab to upload or creates outcomes document displaying the content of the Report (for example in PDF, text, HTML or markdown files). The Content of the document is displayed to ease the access of Knowledge through a readable format. As described here.</li> <li>Entities: A table containing all SDO (Stix Domain Objects) contained in the Report, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables: A table containing all SCO (Stix Cyber Observable) contained in the Report, with search and filters available. It also displays if the SCO has been added directly or through inferences with the reasoning engine</li> <li>Data: as described here.</li> </ul> <p>Exploring and modifying the structured Knowledge contained in a Report can be done through different lenses.</p>"},{"location":"usage/exploring-analysis/#graph-view","title":"Graph View","text":"<p>In Graph view, STIX SDO are displayed as graph nodes and relationships as graph links. Nodes are colored depending of their type. Direct relationship are displayed as plain link and inferred relationships in dotted link. At the top right, you will find a serie of icons. From there you can change the current type of view. Here you can also perform global action on the Knowledge of the Report. Let's highlight 2 of them: - Suggestions: This tool suggests you some logical relationships to add between your contained Object to give more consistency to your Knowledge. - Share with an Organization: if you have designated a main Organization in the platform settings, you can here share your Report and its content with users of an other Organization. At the bottom, you have many option to manipulate the graph: - Multiple option for shaping the graph and applying forces to the nodes and links - Multiple selection options - Multiple filters, including a time range selector allowing you to see the evolution of the Knowledge within the Report. - Multiple creation and edition tools to modify the Knowledge contained in the Report.</p>"},{"location":"usage/exploring-analysis/#content-mapping-view","title":"Content mapping view","text":"<p>Through this view, you can map exsisting or new Objects directly from a readable content, allowing you to quickly append structured Knowledge in your Report before refining it with relationships and details.  This view is a great place to see the continuum between unstructured and structured Knowledge of a specific Intelligence Production.</p>"},{"location":"usage/exploring-analysis/#timeline-view","title":"Timeline view","text":"<p>This view allows you to see the structured Knowledge chronologically. This view is really useful when the report describes an attack or a campaign that lasted some time, and the analyst payed attention to the dates. The view can be filtered and displayed relationships too.</p>"},{"location":"usage/exploring-analysis/#correlation-view","title":"Correlation view","text":"<p>The correlation view is a great way to visualize and find other Reports related to your current subject of interest. This graph displays all Report related to the important nodes contained in your current Report, for example Objects like Malware or Intrusion sets.</p>"},{"location":"usage/exploring-analysis/#matrix-view","title":"Matrix view","text":"<p>If your Report describes let's say an attack, a campaign, or an understanding of an Intrusion set, it should contains multiple attack patterns Objects to structure the Knowledge about the TTPs of the Threat Actor. Those attack patterns can be displayed as highlighted matrices, by default the MITRE ATT&amp;CK Enterprise matrix. As some matrices can be huge, it can be also filtered to only display attack patterns describes in the Report.</p>"},{"location":"usage/exploring-analysis/#groupings","title":"Groupings","text":"<p>Groupings are an alternative to Report for grouping Objects sharing a context without describing an Intelligence Production.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Grouping</code> is defined as such :</p> <p>A Grouping object explicitly asserts that the referenced STIX Objects have a shared context, unlike a STIX Bundle (which explicitly conveys no context). A Grouping object should not be confused with an intelligence product, which should be conveyed via a STIX Report. A STIX Grouping object might represent a set of data that, in time, given sufficient analysis, would mature to convey an incident or threat report as a STIX Report object. For example, a Grouping could be used to characterize an ongoing investigation into a security event or incident. A Grouping object could also be used to assert that the referenced STIX Objects are related to an ongoing analysis process, such as when a threat analyst is collaborating with others in their trust community to examine a series of Campaigns and Indicators.</p> <p>When clicking on the Groupings tab at the top of the interface, you see the list of all the Groupings you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the groupings.</p> <p>Clicking on a Grouping, you land on its Overview tab. For a Groupings, the following tabs are accessible: - Overview: as described here. - Knowledge: a complex tab that regroups all the structured Knowledge contained in the groupings, as for a Report, except for the Timeline view. As described here. - Entities: A table containing all SDO (Stix Domain Objects) contained in the Grouping, with search and filters available. It also display if the SDO has been added directly or through inferences with the reasonging engine - Observables: A table containing all SCO (Stix Cyber Observable) contained in the Grouping, with search and filters available. It also display if the SDO has been added directly or through inferences with the reasonging engine - Data: as described here.</p>"},{"location":"usage/exploring-analysis/#malware-analyses","title":"Malware Analyses","text":"<p>Malware analyses are an important part of the Cyber Threat Intelligence, allowing an precise understanding of what and how a malware really do on the host but also how and from where it receives its command and communicates its results.</p> <p>In OpenCTI, Malware Analyses can be created from enrichment connectors that will take an Observable as input and perform a scan on a online service platform to bring back results. As such, Malware Analyses can be done on File, Domain and URL.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Malware Analyses</code> is defined as such :</p> <p>Malware Analyses captures the metadata and results of a particular static or dynamic analysis performed on a malware instance or family.</p> <p>When clicking on the Malware Analyses tab at the top of the interface, you see the list of all the Malware Analyses you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the Malware Analyses.</p> <p>Clicking on a Malware Analyses, you land on its Overview tab. The following tabs are accessible: - Overview: This view contains some additions from the common Overview here. You will find here details about how the analysis have been performed, what is the global result regarding the malicioussness of the analysed artifact and all the Observables that have been found during the analysis.  - Knowledge: If you Malware analysis is linked to other Objects that are not part of the analysis result, they will be displayed here. As described here. - Data: as described here. - History: as described here.</p> <p></p>"},{"location":"usage/exploring-analysis/#notes","title":"Notes","text":"<p>Not every Knowledge can be structured. For allowing any users to share their insights about a specific Knowledge, they can create a Note for every Object and relationship in OpenCTI they can access to. All the Notes are listed within the Analyses menu for allowing global review of this unstructured addition to the global Knowledge.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Note</code> is defined as such :</p> <p>A Note is intended to convey informative text to provide further context and/or to provide additional analysis not contained in the STIX Objects, Marking Definition objects, or Language Content objects which the Note relates to. Notes can be created by anyone (not just the original object creator).</p> <p>Clicking on a Note, you land on its Overview tab. The following tabs are accessible: - Overview: as described here. - Data: as described here. - History: as described here.</p>"},{"location":"usage/exploring-analysis/#external-references","title":"External references","text":"<p>Intelligence is never created from nothing. External references give user a way to link sources or reference documents to any Object in the platform. All external references are listed within the Analyses menu for accessing directly sources of the structured Knowledge.</p> <p>In the MITRE STIX 2.1 documentation, a <code>External references</code> is defined as such :</p> <p>External references are used to describe pointers to information represented outside of STIX. For example, a Malware object could use an external reference to indicate an ID for that malware in an external database or a report could use references to represent source material.</p> <p>Clicking on an External reference, you land on its Overview tab. The following tabs are accessible: - Overview: as described here.</p>"},{"location":"usage/exploring-arsenal/","title":"Arsenal","text":"<p>When you click on \"Arsenal\" in the left-side bar, you access all the \"Arsenal\" tabs, visible on the top bar on the left. By default, the user directly access the \"Malware\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Arsenal</code> section, users can access the following tabs:</p> <ul> <li><code>Malware</code>: <code>Malware</code> represents any piece of code specifically designed to damage, disrupt, or gain unauthorized access to computer systems, networks, or user data.</li> <li><code>Channels</code>: <code>Channels</code>, in the context of cybersecurity, refer to places or means through which actors disseminate information. This category is used in particular in the context of FIMI (Foreign Information Manipulation Interference). </li> <li><code>Tools</code>: <code>Tools</code> represent legitimate, installed software or hardware applications on an operating system that can be misused by attackers for malicious purposes. (e.g. LOLBAS).</li> <li><code>Vulnerabilities</code>: <code>Vulnerabilities</code> are weaknesses or that can be exploited by attackers to compromise the security, integrity, or availability of a computer system or network.</li> </ul>"},{"location":"usage/exploring-arsenal/#malware","title":"Malware","text":""},{"location":"usage/exploring-arsenal/#general-presentation","title":"General presentation","text":"<p>Malware encompasses a broad category of malicious pieces of code built, deployed, and operated by intrusion set. Malware can take many forms, including viruses, worms, Trojans, ransomware, spyware, and more. These entities are created by individuals or groups, including state-nations, state-sponsored groups, corporations, or hacktivist collectives.</p> <p>Use the <code>Malware</code> SDO to model and track these threats comprehensively, facilitating in-depth analysis, response, and correlation with other security data.</p> <p>When clicking on the Malware tab on the top left, you see the list of all the Malware you have access to, in respect with your allowed marking definitions. These malware are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, related intrusion sets, countries and sectors they target, and labels. You can then search and filter on some common and specific attributes of Malware.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-a-malware","title":"Visualizing Knowledge associated with a Malware","text":"<p>When clicking on an <code>Malware</code> card you land on its Overview tab. For a Malware, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Malware. Different thematic views are proposed to easily see the victimology, the threat actors and intrusion sets using the Malware, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#channels","title":"Channels","text":""},{"location":"usage/exploring-arsenal/#general-presentation_1","title":"General presentation","text":"<p><code>Channels</code> - such as forums, websites and social media platforms (e.g. Twitter, Telegram) - are mediums for disseminating news, knowledge, and messages to a broad audience. While they offer benefits like open communication and outreach, they can also be leveraged for nefarious purposes, such as spreading misinformation, coordinating cyberattacks, or promoting illegal activities. </p> <p>Monitoring and managing content within <code>Channels</code> aids in analyzing threats, activities, and indicators associated with various threat actors, campaigns, and intrusion sets.</p> <p>When clicking on the Channels tab at the top left, you see the list of all the Channels you have access to, in respect with your allowed marking definitions. These channels are displayed in a list where you can find certain fields characterizing the entity: type of channel, labels, and dates. You can then search and filter on some common and specific attributes of Channels.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-a-channel","title":"Visualizing Knowledge associated with a Channel","text":"<p>When clicking on a <code>Channel</code> in the list, you land on its Overview tab. For a Channel, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Channel. Different thematic views are proposed to easily see the victimology, the threat actors and intrusion sets using the Malware, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#tools","title":"Tools","text":""},{"location":"usage/exploring-arsenal/#general-presentation_2","title":"General presentation","text":"<p><code>Tools</code> refers to legitimate, pre-installed software applications, command-line utilities, or scripts that are present on a compromised system. These objects enable you to model and monitor the activities of these tools, which can be misused by attackers.</p> <p>When clicking on the <code>Tools</code> tab at the top left, you see the list of all the <code>Tools</code> you have access to, in respect with your allowed marking definitions. These tools are displayed in a list where you can find certain fields characterizing the entity: labels and dates. You can then search and filter on some common and specific attributes of Tools.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-an-observed-data","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on a <code>Tool</code> in the list, you land on its Overview tab. For a Tool, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Tool. Different thematic views are proposed to easily see the threat actors, the intrusion sets and the malware using the Tool. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#vulnerabilities","title":"Vulnerabilities","text":""},{"location":"usage/exploring-arsenal/#general-presentation_3","title":"General presentation","text":"<p><code>Vulnerabilities</code> represent weaknesses or flaws in software, hardware, configurations, or systems that can be exploited by malicious actors. This object assists in managing and tracking the organization's security posture by identifying areas that require attention and remediation, while also providing insights into associated intrusion sets, malware and campaigns where relevant.</p> <p>When clicking on the <code>Vulnerabilities</code> tab at the top left, you see the list of all the <code>Vulnerabilities</code> you have access to, in respect with your allowed marking definitions. These vulnerabilities are displayed in a list where you can find certain fields characterizing the entity: CVSS3 severity, labels, dates and creators (in the platform). You can then search and filter on some common and specific attributes of Vulnerabilities.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-an-observed-data_1","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on a <code>Vulnerabilities</code> in the list, you land on its Overview tab. For a Vulnerability, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Vulnerability. Different thematic views are proposed to easily see the threat actors, the intrusion sets and the malware exploiting the Vulnerability. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-cases/","title":"Cases","text":"<p>When you click on \"Cases\" in the left-side bar, you access all the \"Cases\" tabs, visible on the top bar on the left. By default, the user directly access the \"Incident Responses\" tab, but can navigate to the other tabs as well.</p> <p>As Analyses, <code>Cases</code> can contain other objects. This way, by adding context and results of your investigations in the case, you will be able to get an up-to-date overview of the ongoing situation, and later produce more easily an incident report. </p> <p>From the <code>Cases</code> section, users can access the following tabs:</p> <ul> <li><code>Incident Responses</code>: This type of Cases is dedicated to the management of incidents. An Incident Response case does not represent an incident, but all the context and actions that will encompass the response to a specific incident.</li> <li><code>Request for Information</code>: CTI teams are often asked to provide extensive information and analysis on a specific subject, be it related to an ongoing incident or a particular trending threat. Request for Information cases allow you to store context and actions relative to this type of request and its response.</li> <li><code>Request for Takedown</code>: When an organization is targeted by an attack campaign, a typical response action can be to request the Takedown of elements of the attack infrastructure, for example a domain name impersonating the organization to phish its employees, or an email address used to deliver phishing content. As Takedown needs in most case to reach out to external providers and be effective quickly, it often needs specific workflows. Request for Takedown cases give you a dedicated space to manage these specific actions.</li> <li><code>Tasks</code>: In every case, you need tasks to be performed in order to solve it. The Tasks tab allows you to review all created tasks to quickly see past due date, or quickly see every task assigned to a specific user.</li> <li><code>Feedbacks</code>: If you use your platform to interact with other teams and provide them CTI Knowledge, some users may want to give you feedback about it. Those feedbacks can easily be considered as another type of case to solve, as it will often refer to Knowledge inconsistency or gaps.</li> </ul> <p></p>"},{"location":"usage/exploring-cases/#incident-response-request-for-information-request-for-takedown","title":"Incident Response, Request for Information &amp; Request for Takedown","text":""},{"location":"usage/exploring-cases/#general-presentation","title":"General presentation","text":"<p>Incident responses, Request for Information &amp; Request for Takedown cases are an important part of the case management system in OpenCTI. Here, you can organize the work of your team to respond to cybersecurity situations. You can also give context to the team and other users on the platform about the situation and actions (to be) taken.</p> <p>To manage the situation, you can issue <code>Tasks</code> and assign them to users in the platform, by directly creating a Task or by applying a Case template that will append a list of predefined tasks.</p> <p>To bring context, you can use your Case as a container (like Reports or Groupings), allowing you to add any Knowledge from your platform in it. You can also use this possibility to trace your investigation, your Case playing the role of an Incident report. You will find more information about case management here.</p> <p>Incident Response, Request for Information &amp; Request for Takedown are not STIX 2.1 Objects.</p> <p>When clicking on the Incident Response, Request for Information &amp; Request for Takedown tabs at the top, you see the list of all the Cases you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes.</p>"},{"location":"usage/exploring-cases/#visualizing-knowledge-within-an-incident-response-request-for-information-request-for-takedown","title":"Visualizing Knowledge within an Incident Response, Request for Information &amp; Request for Takedown","text":"<p>When clicking on an Incident Response, Request for Information or Request for Takedown, you land on the Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: Overview of Cases are slightly different from the usual (described here). Cases' Overview displays also the list of the tasks associated with the case. It also let you highlight Incident, Report or Sighting at the origin of the case. If other cases contains some Observables with your Case, they will be displayed as Related Cases in the Overview.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge contained in the Case, accessible through different views (See below for a dive-in). As described here.</li> <li>Content: a tab to upload or creates outcomes document displaying the content of the Case (for example in PDF, text, HTML or markdown files). The Content of the document is displayed to ease the access of Knowledge through a readable format. As described here.</li> <li>Entities: A table containing all SDO (Stix Domain Objects) contained in the Case, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables: A table containing all SCO (Stix Cyber Observable) contained in the Case, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Data: as described here.</li> </ul> <p>Exploring and modifying the structured Knowledge contained in a Case can be done through different lenses.</p>"},{"location":"usage/exploring-cases/#graph-view","title":"Graph View","text":"<p>In Graph view, STIX SDO are displayed as graph nodes and relationships as graph links. Nodes are colored depending on their type. Direct relationship are displayed as plain link and inferred relationships in dotted link. At the top right, you will find a series of icons. From there you can change the current type of view. Here you can also perform global action on the Knowledge of the Case. Let's highlight 2 of them:</p> <ul> <li>Suggestions: This tool suggests you some logical relationships to add between your contained Object to give more consistency to your Knowledge.</li> <li>Share with an Organization: if you have designated a main Organization in the platform settings, you can here share your Case and its content with users of another Organization. At the bottom, you have many option to manipulate the graph:</li> <li>Multiple option for shaping the graph and applying forces to the nodes and links</li> <li>Multiple selection options</li> <li>Multiple filters, including a time range selector allowing you to see the evolution of the Knowledge within the Case.</li> <li>Multiple creation and edition tools to modify the Knowledge contained in the Case.</li> </ul>"},{"location":"usage/exploring-cases/#content-mapping-view","title":"Content mapping view","text":"<p>Through this view, you can map existing or new Objects directly from a readable content, allowing you to quickly append structured Knowledge in your Case before refining it with relationships and details. This view is a great place to see the continuum between unstructured and structured Knowledge.</p>"},{"location":"usage/exploring-cases/#timeline-view","title":"Timeline view","text":"<p>This view allows you to see the structured Knowledge chronologically. This view is particularly useful in the context of a Case, allowing you to see the chain of events, either from the attack perspectives, the defense perspectives or both. The view can be filtered and displayed relationships too.</p>"},{"location":"usage/exploring-cases/#matrix-view","title":"Matrix view","text":"<p>If your Case contains attack patterns, you will be able to visualize them in a Matrix view.</p>"},{"location":"usage/exploring-cases/#tasks","title":"Tasks","text":"<p>Tasks are actions to be performed in the context of a Case (Incident Response, Request for Information, Request for Takedown). Usually, a task is assigned to a user, but important tasks may involve more participants.</p> <p>When clicking on the Tasks tab at the top of the interface, you see the list of all the Tasks you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the tasks.</p> <p>Clicking on a Task, you land on its Overview tab. For a Tasks, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-cases/#feedbacks","title":"Feedbacks","text":"<p>When a user fill a feedback form from its Profile/Feedback menu, it will then be accessible here.</p> <p>This feature gives the opportunity to engage with other users of your platform and to respond directly to their concern about it or the Knowledge, without the need of third party software.</p> <p></p> <p>Clicking on a Feedback, you land on its Overview tab. For a Feedback, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Content: as described here. </li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-entities/","title":"Entities","text":"<p>OpenCTI's Entities objects provides a comprehensive framework for modeling various targets and attack victims within your threat intelligence data. With five distinct Entity object types, you can represent sectors, events, organizations, systems, and individuals. This robust classification empowers you to contextualize threats effectively, enhancing the depth and precision of your analysis.</p> <p>When you click on \"Entities\" in the left-side bar, you access all the \"Entities\" tabs, visible on the top bar on the left. By default, the user directly access the \"Sectors\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Entities</code> section, users can access the following tabs:</p> <ul> <li><code>Sectors</code>: areas of activity.</li> <li><code>Events</code>: event in the real world.</li> <li><code>Organizations</code>: groups with specific aims such as companies and government entities.</li> <li><code>Systems</code>: technologies such as platforms and software.</li> <li><code>Individuals</code>: real persons.</li> </ul>"},{"location":"usage/exploring-entities/#sectors","title":"Sectors","text":""},{"location":"usage/exploring-entities/#general-presentation","title":"General presentation","text":"<p>Sectors represent specific domains of activity, defining areas such as energy, government, health, finance, and more. Utilize sectors to categorize targeted industries or sectors of interest, providing valuable context for threat intelligence analysis within distinct areas of the economy.</p> <p>When clicking on the Sectors tab at the top left, you see the list of all the Sectors you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-a-sector","title":"Visualizing Knowledge associated with a Sector","text":"<p>When clicking on a <code>Sector</code> in the list, you land on its Overview tab. For a Sector, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Sector. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Sector. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Sector.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-entities/#events","title":"Events","text":""},{"location":"usage/exploring-entities/#general-presentation_1","title":"General presentation","text":"<p>Events encompass occurrences like international sports events, summits (e.g., G20), trials, conferences, or any significant happening in the real world. By modeling events, you can analyze threats associated with specific occurrences, allowing for targeted investigations surrounding high-profile incidents.</p> <p>When clicking on the Events tab at the top left, you see the list of all the Events you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-event","title":"Visualizing Knowledge associated with an Event","text":"<p>When clicking on an <code>Event</code> in the list, you land on its Overview tab. For an Event, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Event. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Event. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted during an attack against the Event.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-entities/#organizations","title":"Organizations","text":""},{"location":"usage/exploring-entities/#general-presentation_2","title":"General presentation","text":"<p>Organizations include diverse entities such as companies, government bodies, associations, non-profits, and other groups with specific aims. Modeling organizations enables you to understand the threat landscape concerning various entities, facilitating investigations into cyber-espionage, data breaches, or other malicious activities targeting specific groups.</p> <p>When clicking on the Organizations tab at the top left, you see the list of all the Organizations you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-organization","title":"Visualizing Knowledge associated with an Organization","text":"<p>When clicking on an <code>Organization</code> in the list, you land on its Overview tab. For an Organization, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Organization. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Organization. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Organization.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, an Organization can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the Organization (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the Organization is the author.</li> </ul> <p></p>"},{"location":"usage/exploring-entities/#systems","title":"Systems","text":""},{"location":"usage/exploring-entities/#general-presentation_3","title":"General presentation","text":"<p>Systems represent software applications, platforms, frameworks, or specific tools like WordPress, VirtualBox, Firefox, Python, etc. Modeling systems allows you to focus on threats related to specific software or technology, aiding in vulnerability assessments, patch management, and securing critical applications.</p> <p>When clicking on the Systems tab at the top left, you see the list of all the Systems you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-a-system","title":"Visualizing Knowledge associated with a System","text":"<p>When clicking on a <code>System</code> in the list, you land on its Overview tab. For a System, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the System. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the System. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the System.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, a System can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the System (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the System is the author.</li> </ul>"},{"location":"usage/exploring-entities/#individuals","title":"Individuals","text":""},{"location":"usage/exploring-entities/#general-presentation_4","title":"General presentation","text":"<p>Individuals represent specific persons relevant to your threat intelligence analysis. This category includes targeted individuals, or influential figures in various fields. Modeling individuals enables you to analyze threats related to specific people, enhancing investigations into cyber-stalking, impersonation, or other targeted attacks.</p> <p>When clicking on the Individuals tab at the top left, you see the list of all the Individuals you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-individual","title":"Visualizing Knowledge associated with an Individual","text":"<p>When clicking on an <code>Individual</code> in the list, you land on its Overview tab. For an Individual, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Individual. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Individual. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Individual.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, an Individual can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the Individual (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the Individual is the author.</li> </ul>"},{"location":"usage/exploring-events/","title":"Events","text":"<p>When you click on \"Events\" in the left-side bar, you access all the \"Events\" tabs, visible on the top bar on the left. By default, the user directly access the \"Incidents\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Events</code> section, users can access the following tabs:</p> <ul> <li><code>Incidents</code>: In OpenCTI, <code>Incidents</code> correspond to a negative event happening on an information system. This can include a cyberattack (intrusion, phishing, etc.), a consolidated security alert generated by a SIEM or EDR that need to be qualified, and so on. It can also refer to an information warfare attack in the context of countering disinformation.</li> <li><code>Sightings</code>: <code>Sightings</code> correspond to the event in which an <code>Observable</code> (IP, domain name, certificate, etc.) is detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or an EDR.</li> <li><code>Observed Data</code>: <code>Observed Data</code> has been added in OpenCTI by compliance with the STIX 2.1 standard. You can see it has a pseudo-container that contains Observables, like a line of firewall log for example. Currently, it is rarely used.</li> </ul>"},{"location":"usage/exploring-events/#incidents","title":"Incidents","text":""},{"location":"usage/exploring-events/#general-presentation","title":"General presentation","text":"<p>Incidents usually represents negative events impacting resources you want to protect, but local definitions can vary a lot, from a simple security events send by a SIEM to a massive scale supply chain attack impacting a whole activity sector.</p> <p>In the MITRE STIX 2.1, the <code>Incident</code> SDO has not yet been finalized and is the object of important work as part of a forthcoming STIX Extension.</p> <p>When clicking on the Incidents tab at the top left, you see the list of all the Incidents you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-an-incident","title":"Visualizing Knowledge associated with an Incident","text":"<p>When clicking on an <code>Incident</code> in the list, you land on its Overview tab. For an Incident, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display two distribution graphs of its related Entities (STIX SDO) and Observable (STIX SCO).</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Incident. Different thematic views are proposed to easily see the victimology, arsenal, techniques and so on used in the context of the Incident. As described here.</li> <li>Content: This specific tab allows to previzualize, manage and write deliverable associated with the Incident. For example an analytic report to share with other teams, a markdown files to feed a collaborative wiki with, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-events/#sightings","title":"Sightings","text":""},{"location":"usage/exploring-events/#general-presentation_1","title":"General presentation","text":"<p>The <code>Sightings</code> correspond to events in which an <code>Observable</code> (IP, domain name, url, etc.) is detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or EDR. </p> <p>In OpenCTI, as we are in a cybersecurity context, <code>Sightings</code> are associated with <code>Indicators</code> of Compromise (IoC) and the notion of \"True positive\" and \"False positive\". </p> <p>It is important to note that Sightings are a type of relationship (not a STIX SDO or STIX SCO), between an Observable and an Entities or Locations.</p> <p>When clicking on the Sightings tab at the top left, you see the list of all the Sightings you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-a-sighting","title":"Visualizing Knowledge associated with a Sighting","text":"<p>When clicking on a <code>Sighting</code> in the list, you land on its Overview tab. As other relationships in the platform, Sighting's overview displays common related metadata, containers, external references, notes and entities linked by the relationship. </p> <p>In addition, this overview displays: - Qualification : if the Sighting is a True Positive or a False Positive - Count : number of times the event has been seen</p>"},{"location":"usage/exploring-events/#observed-data","title":"Observed Data","text":""},{"location":"usage/exploring-events/#general-presentation_2","title":"General presentation","text":"<p><code>Observed Data</code> correspond to an extract from a log that contains Observables. </p> <p>In the MITRE STIX 2.1, the <code>Observed Data</code> SDO is defined as such:</p> <p>Observed Data conveys information about cybersecurity related entities such as files, systems, and networks using the STIX Cyber-observable Objects (SCOs). For example, Observed Data can capture information about an IP address, a network connection, a file, or a registry key. Observed Data is not an intelligence assertion, it is simply the raw information without any context for what it means.</p> <p>When clicking on the <code>Observed Data</code> tab at the top left, you see the list of all the <code>Observed Data</code> you have access to, in respect with your allowed marking definitions.</p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-an-observed-data","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on an <code>Observed Data</code> in the list, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display a distribution graphs of its related Observables (STIX SCO).</li> <li>Entities : a sortable and filterable list of all Entities (SDO) </li> <li>Observables: a sortable and filterable list of all Observables (SCO) in relation with the Observed Data</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/","title":"Location","text":"<p>OpenCTI's Locations objects provides a comprehensive framework for representing various geographic entities within your threat intelligence data. With five distinct Location object types, you can precisely define regions, countries, areas, cities, and specific positions. This robust classification empowers you to contextualize threats geographically, enhancing the depth and accuracy of your analysis.</p> <p>When you click on \"Locations\" in the left-side bar, you access all the \"Locations\" tabs, visible on the top bar on the left. By default, the user directly access the \"Regions\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Locations</code> section, users can access the following tabs:</p> <ul> <li><code>Regions</code>: very large geographical territories, such as a continent.</li> <li><code>Countries</code>: the world's countries.</li> <li><code>Areas</code>: more or less extensive geographical areas and often not having a very defined limit</li> <li><code>Cities</code>: the world's cities.</li> <li><code>Positions</code>: very precise positions on the globe.</li> </ul>"},{"location":"usage/exploring-locations/#regions","title":"Regions","text":""},{"location":"usage/exploring-locations/#general-presentation","title":"General presentation","text":"<p>Regions encapsulate broader geographical territories, often representing continents or significant parts of continents. Examples include EMEA (Europe, Middle East, and Africa), Asia, Western Europe, and North America. Utilize regions to categorize large geopolitical areas and gain macro-level insights into threat patterns.</p> <p>When clicking on the Regions tab at the top left, you see the list of all the Regions you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-region","title":"Visualizing Knowledge associated with a Region","text":"<p>When clicking on a <code>Region</code> in the list, you land on its Overview tab. For a Region, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Region.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Region. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Region. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a Region.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-locations/#countries","title":"Countries","text":""},{"location":"usage/exploring-locations/#general-presentation_1","title":"General presentation","text":"<p>Countries represent individual nations across the world. With this object type, you can specify detailed information about a particular country, enabling precise localization of threat intelligence data. Countries are fundamental entities in geopolitical analysis, offering a focused view of activities within national borders.</p> <p>When clicking on the Countries tab at the top left, you see the list of all the Countries you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-country","title":"Visualizing Knowledge associated with a Country","text":"<p>When clicking on a <code>Country</code> in the list, you land on its Overview tab. For a Country, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Country.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Country. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Country. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a Country.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#areas","title":"Areas","text":""},{"location":"usage/exploring-locations/#general-presentation_2","title":"General presentation","text":"<p>Areas define specific geographical regions of interest, such as the Persian Gulf, the Balkans, or the Caucasus. Use areas to identify unique zones with distinct geopolitical, cultural, or strategic significance. This object type facilitates nuanced analysis of threats within defined geographic contexts.</p> <p>When clicking on the Areas tab at the top left, you see the list of all the Areas you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-an-area","title":"Visualizing Knowledge associated with an Area","text":"<p>When clicking on an <code>Area</code> in the list, you land on its Overview tab. For an Area, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Area.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Area. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Area. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in an Area.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#cities","title":"Cities","text":""},{"location":"usage/exploring-locations/#general-presentation_3","title":"General presentation","text":"<p>Cities provide granular information about urban centers worldwide. From major metropolises to smaller towns, cities are crucial in understanding localized threat activities. With this object type, you can pinpoint threats at the urban level, aiding in tactical threat assessments and response planning.</p> <p>When clicking on the Cities tab at the top left, you see the list of all the Cities you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-city","title":"Visualizing Knowledge associated with a City","text":"<p>When clicking on a <code>City</code> in the list, you land on its Overview tab. For a City, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the City.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the City. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the City. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a City.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#positions","title":"Positions","text":""},{"location":"usage/exploring-locations/#general-presentation_4","title":"General presentation","text":"<p>Positions represent highly precise geographical points, such as monuments, buildings, or specific event locations. This object type allows you to define exact coordinates, enabling accurate mapping of events or incidents. Positions enhance the granularity of your threat intelligence data, facilitating precise geospatial analysis.</p> <p>When clicking on the Positions tab at the top left, you see the list of all the Positions you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-position","title":"Visualizing Knowledge associated with a Position","text":"<p>When clicking on a <code>Position</code> in the list, you land on its Overview tab. For a Position, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display a map locating the Position.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Position. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Position. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted at a Position.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-observations/","title":"Observations","text":"<p>When you click on \"Observations\" in the left-side bar, you access all the \"Observations\" tabs, visible on the top bar on the left. By default, the user directly access the \"Observables\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Observations</code> section, users can access the following tabs:</p> <ul> <li><code>Observables</code>: An <code>Observable</code> represents an immutable object. Observables can encompass a wide range of entities such as IPv4 addresses, domain names, email addresses, and more.</li> <li><code>Artefacts</code>: In OpenCTI, the <code>Artefacts</code> is a particular Observable. It may contain a file, such as a malware sample.</li> <li><code>Indicators</code>: An <code>Indicator</code> is a detection object. It is defined by a search pattern, which could be expressed in various formats such as STIX, Sigma, YARA, among others.</li> <li><code>Infrastructures</code>: An <code>Infrastructure</code> describes any systems, software services and any associated physical or virtual resources intended to support some purpose (e.g. C2 servers used as part of an attack, devices or servers that are part of defense, database servers targeted by an attack, etc.).</li> </ul>"},{"location":"usage/exploring-observations/#observables","title":"Observables","text":""},{"location":"usage/exploring-observations/#general-presentation","title":"General presentation","text":"<p>An Observable is a distinct entity from the Indicator within OpenCTI and represents an immutable object. Observables can encompass a wide range of entities such as IPv4 addresses, domain names, email addresses, and more. Importantly, Observables don't inherently imply malicious intent, they can include items like legitimate IP addresses or domains associated with an organization. Additionally, they serve as raw data points without the additional detection context found in Indicators.</p> <p>When clicking on the Observables tab at the top left, you see the list of all the Observables you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-observable","title":"Visualizing Knowledge associated with an Observable","text":"<p>When clicking on an <code>Observable</code> in the list, you land on its Overview tab. For an Observable, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display Indicators composed with the Observable.</li> <li>Knowledge: a tab listing all its relationships and nested objects.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Observable</code> (IP, domain name, url, etc.) has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#artefacts","title":"Artefacts","text":""},{"location":"usage/exploring-observations/#general-presentation_1","title":"General presentation","text":"<p>An Artefact is a particular Observable. It may contain a file, such as a malware sample. Files can be uploaded or downloaded in encrypted archives, providing an additional layer of security against potential manipulation of malicious payloads.</p> <p>When clicking on the Artefacts tab at the top left, you see the list of all the Artefacts you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-artefact","title":"Visualizing Knowledge associated with an Artefact","text":"<p>When clicking on an <code>Artefact</code> in the list, you land on its Overview tab. For an Artefact, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to be able to download the attached file.</li> <li>Knowledge: a tab listing all its relationships and nested objects.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Artefact</code> has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#indicators","title":"Indicators","text":""},{"location":"usage/exploring-observations/#general-presentation_2","title":"General presentation","text":"<p>An Indicator is a detection object. It is defined by a search pattern, which could be expressed in various formats such as STIX, Sigma, YARA, among others. This pattern serves as a key to identify potential threats within the data. Furthermore, an Indicator includes additional information that enriches its detection context. This information encompasses:</p> <ul> <li>Validity dates: Indicators are accompanied by a time frame, specifying the duration of their relevance, and modeled by the <code>Valid from</code> and <code>Valid until</code> dates.</li> <li>Actionable fields: Linked to the validity dates, the <code>Revoked</code> and <code>Detection</code> fields can be used to sort Indicators for detection purposes.</li> <li>Kill chain phase: They indicate the phase within the cyber kill chain where they are applicable, offering insights into the progression of a potential threat.</li> <li>Types: Indicators are categorized based on their nature, aiding in classification and analysis.</li> </ul> <p>When clicking on the Indicators tab at the top left, you see the list of all the Indicators you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-indicator","title":"Visualizing Knowledge associated with an Indicator","text":"<p>When clicking on an <code>Indicator</code> in the list, you land on its Overview tab. For an Indicator, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display the Observables on which it is based.</li> <li>Knowledge: a tab listing all its relationships.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Indicator</code> has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#infrastructures","title":"Infrastructures","text":""},{"location":"usage/exploring-observations/#general-presentation_3","title":"General presentation","text":"<p>An Infrastructure refers to a set of resources, tools, systems, or services employed by a threat to conduct their activities. It represents the underlying framework or support system that facilitates malicious operations, such as the command and control (C2) servers in an attack. Notably, like Observables, an Infrastructure doesn't inherently imply malicious intent. It can also represent legitimate resources affiliated with an organization (e.g. devices or servers that are part of defense, database servers targeted by an attack, etc.).</p> <p>When clicking on the Infrastructures tab at the top left, you see the list of all the Infrastructures you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-infrastructure","title":"Visualizing Knowledge associated with an Infrastructure","text":"<p>When clicking on an <code>Infrastructure</code> in the list, you land on its Overview tab. For an Infrastructure, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display distribution graphs of its related Observable (STIX SCO).</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Infrastructure. Different thematic views are proposed to easily see the threats, the arsenal, the observations, etc. linked to the Infrastructure. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/","title":"Techniques","text":"<p>When you click on \"Techniques\" in the left-side bar, you access all the \"Techniques\" tabs, visible on the top bar on the left. By default, the user directly access the \"Attack pattern\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Techniques</code> section, users can access the following tabs:</p> <ul> <li><code>Attack pattern</code>: attacks pattern used by the threat actors to perform their attacks. By default, OpenCTI is provisionned with attack patterns from MITRE ATT&amp;CK matrices (for CTI) and DISARM matrix (for FIMI).</li> <li><code>Narratives</code>: In OpenCTI, narratives used by threat actors can be represented and linked to other Objects. Narratives are mainly used in the context of disinformation campaigns where it is important to trace which narratives have been and are still used by threat actors.</li> <li><code>Courses of action</code>: A Course of Action is an action taken either to prevent an attack or to respond to an attack that is in progress. It may describe technical, automatable responses (applying patches, reconfiguring firewalls) but can also describe higher level actions like employee training or policy changes. For example, a course of action to mitigate a vulnerability could describe applying the patch that fixes it.</li> <li><code>Data sources</code>: Data sources represent the various subjects/topics of information that can be collected by sensors/logs. Data sources also include data components, </li> <li><code>Data components</code>: Data components identify specific properties/values of a data source relevant to detecting a given ATT&amp;CK technique or sub-technique.</li> </ul>"},{"location":"usage/exploring-techniques/#attack-pattern","title":"Attack pattern","text":""},{"location":"usage/exploring-techniques/#general-presentation","title":"General presentation","text":"<p>Attacks pattern used by the threat actors to perform their attacks. By default, OpenCTI is provisionned with attack patterns from MITRE ATT&amp;CK matrices and CAPEC (for CTI) and DISARM matrix (for FIMI).</p> <p>In the MITRE STIX 2.1 documentation, an <code>Attack pattern</code> is defined as such :</p> <p>Attack Patterns are a type of TTP that describe ways that adversaries attempt to compromise targets. Attack Patterns are used to help categorize attacks, generalize specific attacks to the patterns that they follow, and provide detailed information about how attacks are performed. An example of an attack pattern is \"spear phishing\": a common type of attack where an attacker sends a carefully crafted e-mail message to a party with the intent of getting them to click a link or open an attachment to deliver malware. Attack Patterns can also be more specific; spear phishing as practiced by a particular threat actor (e.g., they might generally say that the target won a contest) can also be an Attack Pattern.</p> <p>When clicking on the Attack pattern tab at the top left, you access the list of all the attack pattern you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of attack patterns.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-an-attack-pattern","title":"Visualizing Knowledge associated with an Attack pattern","text":"<p>When clicking on an Attack pattern, you land on its Overview tab. For an Attack pattern, the following tabs are accessible:</p> <ul> <li> <p>Overview: Overview of Attack pattern is a bit different as the usual described here. The \"Details\" box is more structured and contains information about:</p> </li> <li> <p>parent or subtechniques (as in the MITRE ATT&amp;CK matrices), </p> </li> <li>related kill chain phases</li> <li>Platform on which the Attack pattern is usable,</li> <li>permission required to apply it</li> <li>Related detection technique</li> <li>Courses of action to mitigate the Attack pattern</li> <li>Data components in which find data to detect the usage of the Attack pattern</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Attack pattern. Different thematic views are proposed to easily see Threat Actors and Intrusion Sets using this techniques, linked incidents, etc.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#narratives","title":"Narratives","text":""},{"location":"usage/exploring-techniques/#general-presentation_1","title":"General presentation","text":"<p>In OpenCTI, narratives used by threat actors can be represented and linked to other Objects. Narratives are mainly used in the context of disinformation campaigns where it is important to trace which narratives have been and are still used by threat actors.</p> <p>An example of Narrative can be \"The country A is weak and corrupted\" or \"The ongoing operation aims to free people\". </p> <p>Narrative can be a mean in the context of a more broad attack or the goal of the operation, a vision to impose.</p> <p>When clicking on the Narrative tab at the top left, you access the list of all the Narratives you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of narratives.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-narrative","title":"Visualizing Knowledge associated with a Narrative","text":"<p>When clicking on a Narrative, you land on its Overview tab. For a Narrative, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Narratives. Different thematic views are proposed to easily see the Threat actors and Intrusion Set using the Narrative, etc. </li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#courses-of-action","title":"Courses of action","text":""},{"location":"usage/exploring-techniques/#general-presentation_2","title":"General presentation","text":"<p>In the MITRE STIX 2.1 documentation, an <code>Course of action</code> is defined as such :</p> <p>A Course of Action is an action taken either to prevent an attack or to respond to an attack that is in progress. It may describe technical, automatable responses (applying patches, reconfiguring firewalls) but can also describe higher level actions like employee training or policy changes. For example, a course of action to mitigate a vulnerability could describe applying the patch that fixes it.</p> <p>When clicking on the <code>Courses of action</code> tab at the top left, you access the list of all the Courses of action you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of course of action.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-course-of-action","title":"Visualizing Knowledge associated with a Course of action","text":"<p>When clicking on a <code>Course of Action</code>, you land on its Overview tab. For a Course of action, the following tabs are accessible:</p> <ul> <li>Overview: Overview of Course of action is a bit different as the usual described here. In \"Details\" box, mitigated attack pattern are listed.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Narratives. Different thematic views are proposed to easily see the Threat actors and Intrusion Set using the Narrative, etc. </li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#data-sources-data-components","title":"Data sources &amp; Data components","text":""},{"location":"usage/exploring-techniques/#general-presentation_3","title":"General presentation","text":"<p>In the MITRE ATT&amp;CK documentation, <code>Data sources</code> are defined as such :</p> <p>Data sources represent the various subjects/topics of information that can be collected by sensors/logs. Data sources also include data components, which identify specific properties/values of a data source relevant to detecting a given ATT&amp;CK technique or sub-technique.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-data-source-or-a-data-components","title":"Visualizing Knowledge associated with a Data source or a Data components","text":"<p>When clicking on a <code>Data source</code> or a <code>Data component</code>, you land on its Overview tab. For a Course of action, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/","title":"Threats","text":"<p>When you click on \"Threats\" in the left-side bar, you access all the \"Threats\" tabs, visible on the top bar on the left. By default, the user directly access the \"Threat Actor (Group)\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Threats</code> section, users can access the following tabs:</p> <ul> <li><code>Threat actors (Group)</code>: Threat actor (Group) represents a physical group of attackers operating an Intrusion set, using malware and attack infrastructure, etc.</li> <li><code>Threat actors (Indvidual)</code>: Threat actor (Individual) represents a real attacker that can be described by physical and personal attributes and motivations. Threat actor (Individual) operates Intrusion set, uses malware and infrastructure, etc.</li> <li><code>Intrusion sets</code>: Intrusion set is an important concept in Cyber Threat Intelligence field. It is a consistent set of technical and non-technical elements corresponding of what, how and why a Threat actor acts. it is particularly useful for associating multiple attacks and malicious actions to a defined Threat, even without sufficient information regarding who did them. Often, with you understanding of the threat growing, you will link an Intrusion set to a Threat actor (either a Group or an Individual).</li> <li><code>Campaigns</code>: Campaign represents a series of attacks taking place in a certain period of time and/or targeting a consistent subset of Organization/Individual.</li> </ul>"},{"location":"usage/exploring-threats/#threat-actors-group-and-individual","title":"Threat actors (Group and Individual)","text":""},{"location":"usage/exploring-threats/#general-presentation","title":"General presentation","text":"<p>Threat actors are the humans who are building, deploying and operating intrusion sets. A threat actor can be an single individual or a group of attackers (who may be composed of individuals). A group of attackers may be a state-nation, a state-sponsored group, a corporation, a group of hacktivists, etc. </p> <p>Beware, groups of attackers might be modelled as \"Intrusion sets\" in feeds, as there is sometimes a misunderstanding in the industry between group of people and the technical/operational intrusion set they operate.</p> <p></p> <p>When clicking on the Threat actor (Group or Individual) tabs at the top left, you see the list of all the groups of Threat actors or Individual Threat actors you have access to, in respect with your allowed marking definitions. These groups or individual are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware they used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Threat actors.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#demographic-and-biographic-information","title":"Demographic and Biographic Information","text":"<p>Individual Threat actors have unique properties to represent demographic and biographic information. Currently tracked demographics include their countries of residence, citizenships, date of birth, gender, and more.</p> <p></p> <p>Biographic information includes their eye and hair color, as well as known heights and weights.</p> <p></p> <p>An Individual Threat actor can also be tracked as employed by an Organization or a Threat Actor group. This relationship can be set under the knowledge tab.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-a-threat-actor","title":"Visualizing Knowledge associated with a Threat actor","text":"<p>When clicking on a Threat actor Card, you land on its Overview tab. For a Threat actor, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Threat actor. Different thematic views are proposed to easily see the victimology, arsenal and techniques used by the Threat actor, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/#intrusion-sets","title":"Intrusion Sets","text":"<p>An intrusion set is a consistent group of technical elements such as \"tactics, technics and procedures\" (TTP), tools, malware and infrastructure used by a threat actor against one or a number of victims who are usually sharing some characteristics (field of activity, country or region) to reach a similar goal whoever the victim is. The intrusion set may be deployed once or several times and may evolve with time. Several intrusion sets may be linked to one threat actor. All the entities described below may be linked to one intrusion set. There are many debates in the Threat Intelligence community on how to define an intrusion set and how to distinguish several intrusion sets with regards to:</p> <ul> <li>their differences</li> <li>their evolutions</li> <li>the possible reuse</li> <li>\"false flag\" type of attacks</li> </ul> <p>As OpenCTI is very customizable, each organization or individual may use these categories as they wish. Instead, it is also possible to use the import feed for the choice of categories.</p> <p></p> <p>When clicking on the Intrusion set tab on the top left, you see the list of all the Intrusion sets you have access to, in respect with your allowed marking definitions. These intrusion sets are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware they used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Intrusion set.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-an-intrusion-set","title":"Visualizing Knowledge associated with an Intrusion set","text":"<p>When clicking on an Intrusion set Card, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Intrusion Set. Different thematic views are proposed to easily see the victimology, arsenal and techniques used by the Intrusion Set, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/#campaigns","title":"Campaigns","text":"<p>A campaign can be defined as \"a series of malicious activities or attacks (sometimes called a \"wave of attacks\") taking place within a limited period of time, against a defined group of victims, associated to a similar intrusion set and characterized by the use of one or several identical malware towards the various victims and common TTPs\". However, a campaign is an investigation element and may not be widely recognized. Thus, a provider might define a series of attacks as a campaign and another as an intrusion set. Campaigns can be attributed to an Intrusion set.</p> <p></p> <p>When clicking on the Campaign tab on the top left, you see the list of all the Campaigns you have access to, in respect with your allowed marking definitions. These campaigns are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Campaigns.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-a-campaign","title":"Visualizing Knowledge associated with a Campaign","text":"<p>When clicking on an Campaign Card, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Campaign. Different thematic views are proposed to easily see the victimology, arsenal and techniques used in the context of the Campaign. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/export/","title":"Manual export","text":""},{"location":"usage/export/#introduction","title":"Introduction","text":"<p>With the OpenCTI platform, you can manually export your intelligence content in the following formats:</p> <ul> <li>JSON,</li> <li>CSV,</li> <li>PDF,</li> <li>TXT.</li> </ul> <p></p>"},{"location":"usage/export/#export-in-structured-or-document-format","title":"Export in structured or document format","text":""},{"location":"usage/export/#generate-an-export","title":"Generate an export","text":"<p>To export one or more entities you have two possibilities. First you can click on the button \"Open export panel\". The list of pre-existing exports will open, and in the bottom right-hand corner you can configure and generate a new export.</p> <p> This opens the export settings panel, where you can customize your export according to four fields:</p> <ul> <li>desired export format (text/csv, application/pdf, application/vnd.oasis.stix+json, text/plain)</li> <li>export type (simple or full),</li> <li>the max marking definition levels of the elements to be included in the export (a TLP level, for instance). 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.</li> <li>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.```</li> </ul> <p></p> <p>The second way is to click directly on the \"Generate an Export\" button to export the content of an entity in the desired format. The same settings panel will open.</p> <p></p> <p>Both ways add your export in the Exported files list in the Data tab. </p>"},{"location":"usage/export/#export-possibilities","title":"Export possibilities","text":"<p>All entities in your instance can be exported either directly via Generate Export or indirectly via Export List in .json and .csv formats.</p>"},{"location":"usage/export/#export-a-list-entities","title":"Export a list entities","text":"<p>You have the option to export either a single element, such as a report, or a collection of elements, such as multiple reports. These exports may contain not only the entity itself but also related elements, depending on the type of export you select: \"simple\" or \"full\". See the Export types (simple and full) section.</p> <p>You can also choose to export a list of entities within a container. To do so, go to the container's entities tab. For example, for a report, if you only want to retrieve entity type attack pattern and indicators to design a detection strategy, go to the entities tab and select specific elements for export.</p> <p></p> <p></p>"},{"location":"usage/export/#export-types-simple-and-full","title":"Export types (simple and full)","text":"<p>When you wish to export only the content of a specific entity such as a report, you can choose a \"simple\" export type.</p> <p>If you also wish to export associated content, you can choose a \"full\" export. With this type of export, the entity will be exported along with all entities directly associated with the central one (first neighbors).</p> <p></p>"},{"location":"usage/export/#exports-list-panel","title":"Exports list panel","text":"<p>Once an export has been created, you can find it in the export list panel. Simply click on a particular export to download it.</p> <p>You can also generate a new export directly from the Exports list, as explained in the Generate an export section.</p> <p></p>"},{"location":"usage/feeds/","title":"Native feeds","text":"<p>OpenCTI provides versatile mechanisms for sharing data through its built-in feeds, including Live streams, TAXII collections, and CSV feeds.</p>"},{"location":"usage/feeds/#feed-configuration","title":"Feed configuration","text":"<p>Feeds are configured in the \"Data &gt; Data sharing\" window. Configuration for all feed types is uniform and relies on the following parameters:</p> <ul> <li>Filter setup: The feed can have specific filters to publish only a subset of the platform overall knowledge. Any data that meets the criteria established by the user's feed filters will be shared (e.g. specific types of entities, labels, marking definitions, etc.).</li> <li>Access control: A feed can be either public, i.e. accessible without authentication, or restricted. By default, it's accessible to any user with the \"Access data sharing\" capability, but it's possible to increase restrictions by limiting access to a specific user, group, or organization.</li> </ul> <p></p> <p>By carefully configuring filters and access controls, you can tailor the behavior of Live streams, TAXII collections, and CSV feeds to align with your specific data-sharing needs.</p> <p></p>"},{"location":"usage/feeds/#live-streams","title":"Live streams","text":""},{"location":"usage/feeds/#introduction","title":"Introduction","text":"<p>Live streams, an exclusive OpenCTI feature, increase the capacity for real-time data sharing by serving STIX 2.1 bundles as TAXII collections with advanced capabilities. What distinguishes them is their dynamic nature, which includes the creation, updating, and deletion of data. Unlike TAXII, Live streams comprehensively resolve relationships and dependencies, ensuring a more nuanced and interconnected exchange of information. This is particularly beneficial in scenarios where sharing involves entities with complex relationships, providing a richer context for the shared data.</p> <p>In scenarios involving data sharing between two OpenCTI platforms, Live streams emerge as the preferred mechanism. These streams operate like TAXII collections but are notably enhanced, supporting:</p> <ul> <li>create, update and delete events depending on the parameters,</li> <li>caching already created entities in the last 5 minutes,</li> <li>resolving relationships and dependencies even out of the filters,</li> <li>can be public (without authentication).</li> </ul> <p></p> <p>Resolve relationships and dependencies</p> <p>Dependencies and relationships of entities shared via Live streams, as determined by specified filters, are automatically shared even beyond the confines of these filters. This means that interconnected data, which may not directly meet the filter criteria, is still included in the Live stream. However, OpenCTI data segregation mechanisms are still applied. They allow to restrict access to shared data based on factors such as markings or organization. It's imperative to carefully configure and manage these access controls to ensure that no confidential data is shared.</p>"},{"location":"usage/feeds/#illustrative-scenario","title":"Illustrative scenario","text":"<p>To better understand how live streams are working, let's take a few examples, from simple to complex.</p> <p>Given a live stream with filters Entity type: Indicator <code>AND</code> Label: detection. Let's see what happens with an indicator with:</p> <ul> <li>Marking definition: <code>TLP:GREEN</code></li> <li>Author <code>Crowdstrike</code></li> <li>Relation <code>indicates</code> to the malware <code>Emotet</code></li> </ul> Action Result in stream (with <code>Avoid dependencies resolution=true</code>) Result in stream (with <code>Avoid dependencies resolution=false</code>) 1. Create an indicator Nothing Nothing 2. Add the label <code>detection</code> Create <code>TLP:GREEN</code>, create <code>CrowdStrike</code>, create the indicator Create <code>TLP:GREEN</code>, create <code>CrowdStrike</code>, create the malware <code>Emotet</code>, create the indicator, create the relationship <code>indicates</code> 3. Remove the label <code>detection</code> Delete the indicator Delete the indicator and the relationship 4. Add the label <code>detection</code> Create the indicator Create the indicator, create the relationship <code>indicates</code> 5. Delete the indicator Delete the indicator Delete the indicator  and the relationship <p>Details on how to consume these Live streams can be found on the dedicated page.</p>"},{"location":"usage/feeds/#taxii-collections","title":"TAXII Collections","text":"<p>OpenCTI has an embedded TAXII API endpoint which provides valid STIX 2.1 bundles. If you wish to know more about the TAXII standard, please read the official introduction.</p> <p>In OpenCTI you can create as many TAXII 2.1 collections as needed. </p> <p></p> <p>After creating a new collection, every system with a proper access token can consume the collection using different kinds of authentication (basic, bearer, etc.). </p> <p>As when using the GraphQL API, TAXII 2.1 collections have a classic pagination system that should be handled by the consumer. Also, it's important to understand that element dependencies (nested IDs) inside the collection are not always contained/resolved in the bundle, so consistency needs to be handled at the client level.</p> <p></p>"},{"location":"usage/feeds/#csv-feeds","title":"CSV feeds","text":"<p>The CSV feed facilitates the automatic generation of a CSV file, accessible via a URL. The CSV file is regenerated and updated at user-defined intervals, providing flexibility. The entries in the file correspond to the information that matches the filters applied and that were created or modified in the platform during the time interval (between the last generation of the CSV and the new one).</p> <p></p> <p>CSV size limit</p> <p>The CSV file generated has a limit of 5 000 entries. If more than 5 000 entities are retrieved by the platform, only the most recent 5 000 will be shared in the file.</p>"},{"location":"usage/getting-started/","title":"Getting started","text":"<p>This guide aims to give you a full overview of the OpenCTI features and workflows. The platform can be used in various contexts to handle threats management use cases from a technical to a more strategic level. OpenCTI has been designed as a knowledge graph, taking inputs (threat intelligence feeds, sightings &amp; alerts, vulnerabilities, assets, artifacts, etc.) and generating outputs based on built-in capabilities and / or connectors.</p> <p>Here are some examples of use cases:</p> <ul> <li>Cyber Threat Intelligence knowledge base</li> <li>Detection as code feeds for XDR, EDR, SIEMs, firewalls, proxies, etc.</li> <li>Incident response artifacts &amp; cases management</li> <li>Vulnerabilities management</li> <li>Reporting, alerting and dashboarding on a subset of data</li> </ul> <p></p> <p></p>"},{"location":"usage/getting-started/#welcome-dashboard","title":"Welcome dashboard","text":"<p>The welcome page gives any visitor on the OpenCTI platform an overview of what's happening on the platform. It can be replaced by a custom dashboard, created by a user (or the default dashboard set up in a role, a group or an organization).</p> <p></p>"},{"location":"usage/getting-started/#indicators-in-the-dashboard","title":"Indicators in the dashboard","text":""},{"location":"usage/getting-started/#numbers","title":"Numbers","text":"Component Description Intrusion sets Number of intrusion sets       . Malware Number of malware. Reports Number of reports. Indicators Number of indicators."},{"location":"usage/getting-started/#charts-lists","title":"Charts &amp; lists","text":"Component Description Most active threats (3 last months) Top active threats (threat actor, intrusion set and campaign) during the last 3 months. Most targeted victims (3 last months) Intensity of the targeting tied to the number of relations <code>targets</code> for a given entities (organization, sector, location, etc.) during the last 3 months. Relationships created Volume of relationships created over the past 12 months. Most active malware (3 last months) Top active malware during the last 3 months. Most active vulnerabilities (3 last months) List of the vulnerabilities with the greatest number of relations over the last 3 months. Targeted countries (3 last months) Intensity of the targeting tied to the number of relations <code>targets</code> for a given country over the past 3 months. Latest reports Last reports ingested in the platform. Most active labels (3 last months) Top labels given to entities during the last 3 months. <p>Explore the platform</p> <p>To start exploring the platform and understand how information is structured, we recommend starting with the overview documentation page.</p>"},{"location":"usage/import-automated/","title":"Automated import","text":"<p>Automated imports in OpenCTI streamline the process of data ingestion, allowing users to effortlessly bring in valuable intelligence from diverse sources. This page focuses on the automated methods of importing data, which serve as bridges between OpenCTI and diverse external systems, formatting it into a STIX bundle, and importing it into the OpenCTI platform.</p>"},{"location":"usage/import-automated/#connectors","title":"Connectors","text":"<p>Connectors in OpenCTI serve as dynamic gateways, facilitating the import of data from a wide array of sources and systems. Every connector is designed to handle specific data types and structures of the source, allowing OpenCTI to efficiently ingest the data.</p>"},{"location":"usage/import-automated/#connector-behaviors","title":"Connector behaviors","text":"<p>The behavior of each connector is defined by its development, determining the types of data it imports and its configuration options. This flexibility allows users to customize the import process to their specific needs, ensuring a seamless and personalized data integration experience.</p> <p>The level of configuration granularity regarding the imported data type varies with each connector. Nevertheless, connectors empower users to specify the date from which they wish to fetch data. This capability is particularly useful during the initial activation of a connector, enabling the retrieval of historical data. Following this, the connector operates in real-time, continuously importing new data from the source.</p>"},{"location":"usage/import-automated/#connector-ecosystem","title":"Connector Ecosystem","text":"<p>OpenCTI's connector ecosystem covers a broad spectrum of sources, enhancing the platform's capability to integrate data from various contexts, from threat intelligence providers to specialized databases. The list of available connectors can be found in our connectors catalog. Connectors are categorized into three types: import connectors (the focus here), enrichment connectors, and stream consumers. Further documentation on connectors is available on the dedicated documentation page.</p> <p>In summary, automated imports through connectors empower OpenCTI users with a scalable, efficient, and customizable mechanism for data ingestion, ensuring that the platform remains enriched with the latest and most relevant intelligence.</p>"},{"location":"usage/import-automated/#native-automated-import","title":"Native automated import","text":"<p>In OpenCTI, the \"Data &gt; Ingestion\" section provides users with built-in functions for automated data import. These functions are designed for specific purposes and can be configured to seamlessly ingest data into the platform. Here, we'll explore the configuration process for the four built-in functions: Live Streams, TAXII Feeds, RSS Feeds, and CSV Feeds.</p>"},{"location":"usage/import-automated/#live-streams","title":"Live streams","text":"<p>Live Streams enable users to consume data from another OpenCTI platform, fostering collaborative intelligence sharing. Here's a step-by-step guide to configure Live streams synchroniser:</p> <ol> <li>Remote OpenCTI URL: Provide the URL of the remote OpenCTI platform (e.g., <code>https://[domain]</code>; don't include the path).</li> <li>Remote OpenCTI token: Provide the user token. An administrator from the remote platform must supply this token, and the associated user must have the \"Access data sharing\" privilege.</li> <li>After filling in the URL and user token, validate the configuration.</li> <li>Once validated, select a live stream to which you have access.</li> </ol> <p></p> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this stream. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Starting synchronization: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> <li>Take deletions into account: Enable this option to delete data from your platform if it was deleted on the providing stream. (Note: Data won't be deleted if another source has imported it previously.)</li> <li>Verify SSL certificate: Check the validity of the certificate of the domain hosting the remote platform.</li> <li>Avoid dependencies resolution: Import only entities without their relationships. For instance, if the stream shares malware, all the malware's relationships will be retrieved by default. This option enables you to choose not to recover them.</li> <li>Use perfect synchronization: This option is specifically for synchronizing two platforms. If an imported entity already exists on the platform, the one from the stream will overwrite it.</li> </ul> <p></p>"},{"location":"usage/import-automated/#taxii-feeds","title":"TAXII feeds","text":"<p>TAXII Feeds in OpenCTI provide a robust mechanism for ingesting TAXII collections from TAXII servers or other OpenCTI instances. Configuring TAXII ingester involves specifying essential details to seamlessly integrate threat intelligence data. Here's a step-by-step guide to configure TAXII ingesters:</p> <ol> <li>TAXII server URL: Provide the root API URL of the TAXII server. For collections from another OpenCTI instance, the URL is in the form <code>https://[domain]/taxii2/root</code>.</li> <li>TAXII collection: Enter the ID of the TAXII collection to be ingested. For collections from another OpenCTI instance, the ID follows the format <code>426e3acb-db50-4118-be7e-648fab67c16c</code>.</li> <li>Authentication type (if necessary): Enter the authentication type. For non-public collections from another OpenCTI instance, the authentication type is \"Bearer token.\" Enter the token of a user with access to the collection (similar to the point 2 of the Live streams configuration above).</li> </ol> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this TAXII feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> </ul> <p></p>"},{"location":"usage/import-automated/#rss-feeds","title":"RSS feeds","text":"<p>RSS Feeds functionality enables users to seamlessly ingest items in report form from specified RSS feeds. Configuring RSS Feeds involves providing essential details and selecting preferences to tailor the import process. Here's a step-by-step guide to configure RSS ingesters:</p> <ol> <li>RSS Feed URL: Provide the URL of the RSS feed from which items will be imported.</li> </ol> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this RSS feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> <li>Default report types: Indicate the report type to be applied to the imported report.</li> <li>Default author: Indicate the default author to be applied to the imported report. Please see the section \"Best practices\" below for more information.</li> <li>Default marking definitions: Indicate the default markings to be applied to the imported reports.</li> </ul> <p></p>"},{"location":"usage/import-automated/#csv-feeds","title":"CSV feeds","text":"<p>CSV feed ingester enables users to import CSV files exposed on URLs. Here's a step-by-step guide to configure TAXII ingesters:</p> <ol> <li>CSV URL: Provide the URL of the CSV file exposed from which items will be imported.</li> <li>CSV Mappers: Choose the CSV mapper to be used to import the data.</li> <li>Authentication type (if necessary): Enter the authentication type.</li> </ol> <p>CSV mapper</p> <p>CSV feed functionality is based on CSV mappers. It is necessary to create the appropriate CSV mapper to import the data contained in the file. See the page dedicated to the CSV mapper.</p> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this RSS feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> </ul> <p></p> <p>To finalize the creation, click on \"Verify\" to run a check on the submitted URL with the selected CSV mapper. A valid URL-CSV mapper combination results in the identification of up to 50 entities.</p> <p></p> <p>To start your new ingester, click on \"Start\", in the burger menu.</p> <p></p> <p>CSV feed ingestion is made possible thanks to the connector \"ImportCSV\". So you can track the progress in \"Data &gt; Ingestion &gt; Connectors\". On a regular basis, the ingestion is updated when new data is added to the CSV feed.</p> <p></p> <p></p>"},{"location":"usage/import-automated/#best-practices-for-feed-import","title":"Best practices for feed import","text":"<p>Ensuring a secure and well-organized environment is paramount in OpenCTI. Here are two recommended best practices to enhance security, traceability, and overall organizational clarity:</p> <ol> <li>Create a dedicated user for each source: Generate a user specifically for feed import, following the convention <code>[F] Source name</code> for clear identification. Assign the user to the \"Connectors\" group to streamline user management and permission related to data creation. Please see here for more information on this good practice.</li> <li>Establish a dedicated Organization for the source: Create an organization named after the data source for clear identification. Assign the newly created organization to the \"Default author\" field in feed import configuration if available.</li> </ol> <p>By adhering to these best practices, you ensure independence in managing rights for each import source through dedicated user and organization structures. In addition, you enable clear traceability to the entity's creator, facilitating source evaluation, dashboard creation, data filtering and other administrative tasks.</p>"},{"location":"usage/import-automated/#digest","title":"Digest","text":"<p>Users can streamline the data ingestion process using various automated import capabilities. Each method proves beneficial in specific circumstances.</p> <ul> <li>Connectors act as bridges to retrieve data from diverse sources and format it for seamless ingestion into OpenCTI.</li> <li>Live Streams enable collaborative intelligence sharing across OpenCTI instances, fostering real-time updates and efficient data synchronization.</li> <li>TAXII Feeds provide a standardized mechanism for ingesting threat intelligence data from TAXII servers or other OpenCTI instances.</li> <li>RSS Feeds facilitate the import of items in report form from specified RSS feeds, offering a straightforward way to stay updated on relevant intelligence.</li> </ul> <p>By leveraging these automated import functionalities, OpenCTI users can build a comprehensive, up-to-date threat intelligence database. The platform's adaptability and user-friendly configuration options ensure that intelligence workflows remain agile, scalable, and tailored to the unique needs of each organization.</p>"},{"location":"usage/import-files/","title":"Import from files","text":""},{"location":"usage/import-files/#import-mechanisms","title":"Import mechanisms","text":"<p>The platform provides a seamless process for automatically parsing data from various file formats. This capability is facilitated by two distinct mechanisms.</p> <p>File import connectors: Currently, there are two connectors designed for importing files and automatically identifying entities.</p> <ul> <li><code>ImportFileStix</code>: Designed to handle STIX-structured files (json or xml format).</li> <li><code>ImportDocument</code>: Versatile connector supporting an array of file formats, including pdf, text, html, and markdown.</li> </ul> <p>CSV mappers: The CSV mapper is a tailored functionality to facilitate the import of data stored in CSV files. For more in-depth information on using CSV mappers, refer to the CSV Mappers documentation page.</p> <p></p>"},{"location":"usage/import-files/#usage","title":"Usage","text":""},{"location":"usage/import-files/#locations","title":"Locations","text":"<p>Both mechanisms can be employed wherever file uploads are possible. This includes the \"Data\" tabs of all entities and the dedicated panel named \"Data import and analyst workbenches\" located in the top right-hand corner (database logo with a small gear). Importing files from these two locations is not entirely equal; refer to the \"Relationship handling from entity's Data tab\" section below for details on this matter.</p>"},{"location":"usage/import-files/#entity-identification-process","title":"Entity identification process","text":"<p>For <code>ImportDocument</code> connector, the identification process involves searching for existing entities in the platform and scanning the document for relevant information. In additions, the connector use regular expressions (regex) to detect IP addresses and domains within the document.</p> <p>As for the <code>ImportFileStix</code> connector and the CSV mappers, there is no identification mechanism. The imported data will be, respectively, the data defined in the STIX bundle or according to the configuration of the CSV mapper used.</p>"},{"location":"usage/import-files/#workflow-overview","title":"Workflow overview","text":"<ol> <li>Upload file: Navigate to the desired location, such as the \"Data\" tabs of an entity or the \"Data import and analyst workbenches\" panel. Then, upload the file containing the relevant data by clicking on the small cloud with the arrow inside next to \"Uploaded files\".</li> <li>Entity identification: For a CSV file, select the connector and CSV mapper to be used by clicking on the icon with an upward arrow in a circle. If it's not a CSV file, the connector will launch automatically. Then, the file import connectors or CSV mappers will identify entities within the uploaded document.</li> <li>Workbench review and validation: Entities identified by connectors are not immediately integrated into the platform's knowledge base. Instead, they are thoughtfully placed in a workbench, awaiting review and validation by an analyst. Workbenches function as draft spaces, ensuring that no data is officially entered into the platform until the workbench has undergone the necessary validation process. For more information on workbenches, refer to the Analyst workbench documentation page.</li> </ol> <p>Review workbenches</p> <p>Import connectors may introduce errors in identifying object types or add \"unknown\" entities. Workbenches were established with the intent of reviewing the output of connectors before validation. Therefore, it is crucial to be vigilant when examining the workbench to prevent the import of incorrect data into the platform.</p> <p></p>"},{"location":"usage/import-files/#additional-information","title":"Additional information","text":""},{"location":"usage/import-files/#no-workbench-for-csv-mapper","title":"No workbench for CSV mapper","text":"<p>It's essential to note that CSV mappers operate differently from other import mechanisms. Unlike connectors, CSV mappers do not generate workbenches. Instead, the data identified by CSV mappers is imported directly into the platform without an intermediary workbench stage.</p>"},{"location":"usage/import-files/#relationship-handling-from-entitys-data-tab","title":"Relationship handling from entity's \"Data\" tab","text":"<p>When importing a document directly from an entity's \"Data\" tab, there can be an automatic addition of relationships between the objects identified by connectors and the entity in focus. The process differs depending on the type of entity in which the import occurs:</p> <ul> <li>If the entity is a container (e.g., Report, Grouping, and Cases), the identified objects in the imported file will be linked to the entity (upon workbench validation). In the context of a container, the object is said to be \"contained\".</li> <li>For entities that are not containers, a distinct behavior unfolds. In this scenario, the identified objects are not linked to the entity, except for Observables. <code>Related to</code> relationships between the Observables and the entity are automatically added to the workbench and created after validation of this one.</li> </ul>"},{"location":"usage/import-files/#file-import-in-content-tab","title":"File import in Content tab","text":"<p>Expanding the scope of file imports, users can seamlessly add files in the <code>Content</code> tab of Analyses or Cases. In this scenario, the file is directly added as an attachment without utilizing an import mechanism.</p>"},{"location":"usage/import-files/#user-capability-requirement","title":"User capability requirement","text":"<p>In order to initiate file imports, users must possess the requisite capability: \"Upload knowledge files.\" This capability ensures that only authorized users can contribute and manage knowledge files within the OpenCTI platform, maintaining a controlled and secure environment for data uploads.</p> <p>Deprecation warning</p> <p>Using the <code>ImportDocument</code> connector to parse CSV file is now disallowed as it produces inconsistent results. Please configure and use CSV mappers dedicated to your specific CSV content for a reliable parsing. CSV mappers can be created and configured in the administration interface.   </p>"},{"location":"usage/indicators-lifecycle/","title":"Indicators Lifecycle Management","text":""},{"location":"usage/indicators-lifecycle/#introduction","title":"Introduction","text":"<p>OpenCTI enforces strict rules to determine the period during which an indicator is effective for usage. This period is defined by the <code>valid_from</code> and <code>valid_until</code> dates. All along its lifecycle, the indicator <code>score</code> will decrease according to configured decay rules. After the indicator expires, the object is marked as <code>revoked</code> and the <code>detection</code> field is automatically set to <code>false</code>. Here, we outline how these dates are calculated within the OpenCTI platform and how the score is updated with decay rules.</p>"},{"location":"usage/indicators-lifecycle/#setting-validity-dates","title":"Setting validity dates","text":""},{"location":"usage/indicators-lifecycle/#data-source-provided-the-dates","title":"Data source provided the dates","text":"<p>If a data source provides <code>valid_from</code> and <code>valid_until</code> dates when creating an indicator on the platform, these dates are used without modification. But, if the creation is performed from the UI and the indicator is elligible to be manages by a decay rule, the platform will change this valid_until with the one calculated by the Decay rule.</p>"},{"location":"usage/indicators-lifecycle/#fallback-rules-for-unspecified-dates","title":"Fallback rules for unspecified dates","text":"<p>If a data source does not provide validity dates, OpenCTI applies the decay rule matching the indicator to determine these dates. The <code>valid_until</code> date is computed based on the revoke score of the decay rule : it is set at the exact time at which the indicator will reach the revoke score. Past <code>valid_until</code> date, the indicator is marked as revoked.</p>"},{"location":"usage/indicators-lifecycle/#score-decay","title":"Score decay","text":"<p>Indicators have an initial score at creation, either provided by data source, or 50 by default. Over time, this score is going to decrease according to the configured decay rules. Score is updated at each reaction point defined for the decay rule matching the indicator at creation.</p>"},{"location":"usage/indicators-lifecycle/#example","title":"Example","text":"<p>This URL indicator has matched the <code>Built-in IP and URL</code> decay rule. Its initial score at creation is 100. </p> <p></p> <p>Right next to the indicator score, there is a button <code>Lifecycle</code> which enables to open a dialog to see the details of the indicator's lifecyle.</p> <p></p>"},{"location":"usage/indicators-lifecycle/#conclusion","title":"Conclusion","text":"<p>Understanding how OpenCTI calculates validity periods and scores is essential for effective threat intelligence analysis. These rules ensure that your indicators are accurate and up-to-date, providing a reliable foundation for threat intelligence data.</p>"},{"location":"usage/inferences/","title":"Inferences and reasoning","text":""},{"location":"usage/inferences/#overview","title":"Overview","text":"<p>OpenCTI\u2019s inferences and reasoning capability is a robust engine that automates the process of relationship creation within your threat intelligence data. This capability, situated at the core of OpenCTI, allows logical rules to be applied to existing relationships, resulting in the automatic generation of new, pertinent connections.</p>"},{"location":"usage/inferences/#understanding-inferences-and-reasoning","title":"Understanding inferences and reasoning","text":"<p>Inferences and reasoning serve as OpenCTI\u2019s intelligent engine. It interprets your data logically. By activating specific predefined rules (of which there are around twenty), OpenCTI can deduce new relationships from the existing ones. For instance, if there's a connection indicating an Intrusion Set targets a specific country, and another relationship stating that this country is part of a larger region, OpenCTI can automatically infer that the Intrusion Set also targets the broader region.</p>"},{"location":"usage/inferences/#key-benefits","title":"Key benefits","text":"<ul> <li>Efficiency: Reduces manual workload by automating relationship creation, saving valuable analyst time.</li> <li>Completeness: Fills relationship gaps, ensuring a comprehensive and interconnected threat intelligence database.</li> <li>Accuracy: Minimizes manual input errors by deriving relationships from predefined, accurate logic.</li> </ul>"},{"location":"usage/inferences/#how-it-operates","title":"How it operates","text":"<p>When you activate an inference rule, OpenCTI continuously analyzes your existing relationships and applies the defined logical rules. These rules are logical statements that define conditions for new relationships. When the set of conditions is met, the OpenCTI creates the corresponding relationship automatically.</p> <p>For example, if you activate a rule as follows:</p> <p>IF [Entity A targets Identity B] AND [Identity B is part of Identity C] THEN [Entity A targets Identity C]</p> <p>OpenCTI will apply this rule to existing data. If it finds an Intrusion Set (\"Entity A\") targeting a specific country (\"Identity B\") and that country is part of a larger region (\"Identity C\"), the platform will automatically establish a relationship between the Intrusion Set and the region.</p>"},{"location":"usage/inferences/#identifying-inferred-relationships","title":"Identifying inferred relationships","text":"<p>In the knowledge graphs: Inferred relationships are represented by dotted lines of a different color, distinguishing them from non-inferred relations.</p> <p></p> <p>In the lists: In a relationship list, a magic wand icon at the end of the line indicates relationship created by inference.</p> <p></p>"},{"location":"usage/inferences/#additional-resources","title":"Additional resources","text":"<ul> <li>Administration: To find out about existing inference rules and enable/disable them, refer to the Rules engine page in the Administration section of the documentation.</li> <li>Playbooks: OpenCTI playbooks are highly customizable automation scenarios. This seamless integration allows for further automation, making your threat intelligence processes even more efficient and tailored to your specific needs. More information in our blog post</li> </ul>"},{"location":"usage/manual-creation/","title":"Manual creations","text":"<p>Manual data creation in OpenCTI is an intuitive process that occurs throughout the platform. This page provides guidance on two key aspects of manual creation: Entity creation and Relationship creation.</p>"},{"location":"usage/manual-creation/#entity-creation","title":"Entity creation","text":"<p>To create an entity:</p> <ol> <li>Navigate to the relevant section: Be on the section of the platform related to the object type you want to create.</li> <li>Click on the \"+\" icon: Locate the \"+\" icon located at the bottom right of the window. </li> <li>Fill in entity-specific fields: A form on the right side of the window will appear, allowing to fill in specific fields of the entity. Certain fields are inherently obligatory, and administrators have the option to designate additional mandatory fields (See here for more information). </li> <li>Click on \"Create\": Once you've filled in the desired fields, click on \"create\" to initiate the entity creation process.</li> </ol> <p></p>"},{"location":"usage/manual-creation/#relationship-creation","title":"Relationship creation","text":"<p>Before delving into the creation of relationships between objects in OpenCTI, it's crucial to grasp some foundational concepts. Here are key points to understand:</p> <ul> <li>On several aspects, including relationships, two categories of objects must be differentiated: containers (e.g., Reports, Groupings, and Cases) and others. Containers aren't related to but contains objects.</li> <li>Relationships, like all other entities, are objects. They possess fields, can be linked, and share characteristics identical to other entities.</li> <li>Relationships are inherently directional, comprising a \"from\" entity and a \"to\" entity. Understanding this directionality is essential for accurate relationship creation.</li> <li>OpenCTI supports various relationship types, and their usage depends on the entity types being linked. For example, a \"target\" relationship might link malware to an organization, while linking malware to an intrusion set might involve a different relationship type.</li> </ul> <p>Now, let\u2019s explore the process of creating relationships. To do this, we will differentiate the case of containers from the others. </p>"},{"location":"usage/manual-creation/#for-container","title":"For container","text":"<p>When it comes to creating relationships within containers in OpenCTI, the process is straightforward. Follow these steps to attach objects to a container:</p> <ol> <li>Navigate to the container: Go to the specific container to which you want to attach an object. This could be a Report, Grouping, or Cases.</li> <li>Access the \"Entities\" tab: Within the container, locate and access the \"Entities\" tab.</li> <li>Click on the \"+\" icon: Find the \"+\" icon located at the bottom right of the window. </li> <li>Search for entities: A side window will appear. Search for the entities you want to add to the container. </li> <li>Add entities to the container: Click on the desired entities. They will be added directly to the container.</li> </ol>"},{"location":"usage/manual-creation/#for-other","title":"For other","text":"<p>When creating relationships not involving a container, the creation method is distinct. Follow these steps to create relationships between entities:</p> <ol> <li>Navigate to one of the entities: Go to one of the entities you wish to link. Please be aware that the entity from which you create the relationship will be designated as the \"from\" entity for that relationship. So the decision of which entity to choose for creating the relationship should be considered, as it will impact the outcome. </li> <li>Access the \"Knowledge\" tab: Within the entity, go to the \"Knowledge\" tab.</li> <li>Select the relevant categories: In the right banner, navigate to the categories that correspond to the object to be linked. The available categories depend on the type of entity you are currently on. For example, if you are on malware and want to link to a sector, choose \"victimology.\"</li> <li>Click on the \"+\" icon: Find the \"+\" icon located at the bottom right of the window. </li> <li>Search for entities: A side window will appear. Search for the entities you want to link.</li> <li>Add entities and click on \"Continue\": Click on the entities you wish to link. Multiple entities can be selected. Then click on \"Continue\" at the bottom right. </li> <li>Fill in the relationship form: As relationships are objects, a creation form similar to creating an entity will appear. </li> <li>Click on \"Create\": Once you've filled in the desired fields, click on \"create\" to initiate the relationship creation process.</li> </ol> <p></p>"},{"location":"usage/manual-creation/#additional-methods","title":"Additional methods","text":"<p>While the aforementioned methods are primary for creating entities and relationships, OpenCTI offers versatility, allowing users to create objects in various locations within the platform. Here's a non-exhaustive list of additional places that facilitate on-the-fly creation:</p> <ul> <li>Creating entities during relationship creation: During the \"Search for entities\" phase (see above) of the relationship creation process, click on the \"+\" icon to create a new entity directly.</li> <li>Knowledge graph: Within the knowledge graph - found in the knowledge tab of the containers or in the investigation functionality - users can seamlessly create entities or relationships.</li> <li>Inside a workbench: The workbench serves as another interactive space where users can create entities and relationships efficiently.</li> </ul> <p>These supplementary methods offer users flexibility and convenience, allowing them to adapt their workflow to various contexts within the OpenCTI platform. As users explore the platform, they will naturally discover additional means of creating entities and relationships.</p> <p>Max confidence level</p> <p>When creating knowledge in the platform, the maximum confidence level of the users is used. Please navigate to this page to understand this concept and the impact it can have on the knowledge creation.</p>"},{"location":"usage/merging/","title":"Merge objects","text":""},{"location":"usage/merging/#introduction","title":"Introduction","text":"<p>OpenCTI\u2019s merge capability stands as a pivotal tool for optimizing threat intelligence data, allowing to consolidate multiple entities of the same type. This mechanism serves as a powerful cleanup tool, harmonizing the platform and unifying scattered information. In this section, we explore the significance of this feature, the process of merging entities, and the strategic considerations involved.</p> <p></p>"},{"location":"usage/merging/#data-streamlining","title":"Data streamlining","text":"<p>In the ever-expanding landscape of threat intelligence and the multitude of names chosen by different data sources, data cleanliness is essential. Duplicates and fragmented information hinder efficient analysis. The merge capability is a strategic solution for amalgamating related entities into a cohesive unit. Central to the merging process is the selection of a main entity. This primary entity becomes the anchor, retaining crucial attributes such as name and description. Other entities, while losing specific fields like descriptions, are aliased under the primary entity. This strategic decision preserves vital data while eliminating redundancy.</p>"},{"location":"usage/merging/#preserving-entity-relationships","title":"Preserving entity relationships","text":"<p>One of the key feature of the merge capability is its ability to preserve relationships. While merging entities, their interconnected relationships are not lost. Instead, they seamlessly integrate into the new, merged entity. This ensures that the intricate web of relationships within the data remains intact, fostering a comprehensive understanding of the threat landscape.</p>"},{"location":"usage/merging/#conclusion","title":"Conclusion","text":"<p>OpenCTI\u2019s merge capability helps improve the quality of threat intelligence data. By consolidating entities and centralizing relationships, OpenCTI empowers analysts to focus on insights and strategies, unburdened by data silos or fragmentation. However, exercising caution and foresight in the merging process is essential, ensuring a robust and streamlined knowledge basis.</p>"},{"location":"usage/merging/#additional-resources","title":"Additional resources","text":"<ul> <li>Administration: To understand how to merge entities and the consideration to take into account, refer to the Merging page in the Administration section of the documentation.</li> <li>Deduplication mechanism: the platform is equipped with deduplication processes that automatically merge data at creation (either manually or by importing data from different sources) if it meets certain conditions.</li> </ul>"},{"location":"usage/nested/","title":"Nested references and objects","text":""},{"location":"usage/nested/#stix-standard","title":"STIX standard","text":""},{"location":"usage/nested/#definition","title":"Definition","text":"<p>In the STIX 2.1 standard, objects can:</p> <ol> <li>Refer to other objects in directly in their <code>attributes</code>, by referencing one or multiple IDs.</li> <li>Have other objects directly embedded in the entity.</li> </ol>"},{"location":"usage/nested/#example","title":"Example","text":"<pre><code>{\n   \"type\": \"intrusion-set\",\n   \"spec_version\": \"2.1\",\n   \"id\": \"intrusion-set--4e78f46f-a023-4e5f-bc24-71b3ca22ec29\",\n   \"created_by_ref\": \"identity--f431f809-377b-45e0-aa1c-6a4751cae5ff\", // nested reference to an identity\n   \"object_marking_refs\": [\"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da\"], // nested reference to multiple marking defintions\n   \"external_references\": [\n      {\n         \"source_name\": \"veris\",\n         \"external_id\": \"0001AA7F-C601-424A-B2B8-BE6C9F5164E7\",\n         \"url\": \"https://github.com/vz-risk/VCDB/blob/125307638178efddd3ecfe2c267ea434667a4eea/data/json/validated/0001AA7F-C601-424A-B2B8-BE6C9F5164E7.json\",    \n      }\n   ],\n   \"created\": \"2016-04-06T20:03:48.000Z\",\n   \"modified\": \"2016-04-06T20:03:48.000Z\",\n   \"name\": \"Bobcat Breakin\",\n   \"description\": \"Incidents usually feature a shared TTP of a bobcat being released within the building containing network access...\",\n   \"aliases\": [\"Zookeeper\"],\n   \"goals\": [\"acquisition-theft\", \"harassment\", \"damage\"]\n}\n</code></pre> <p>In the previous example, we have 2 nested references to other objects in:</p> <pre><code>\"created_by_ref\": \"identity--f431f809-377b-45e0-aa1c-6a4751cae5ff\", // nested reference to an identity\n\"object_marking_refs\": [\"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da\"], // nested reference to multiple marking defintions\n</code></pre> <p>But we also have a nested object within the entity (an <code>External Reference</code>):</p> <pre><code>\"external_references\": [\n   {\n      \"source_name\": \"veris\",\n      \"external_id\": \"0001AA7F-C601-424A-B2B8-BE6C9F5164E7\",\n      \"url\": \"https://github.com/vz-risk/VCDB/blob/125307638178efddd3ecfe2c267ea434667a4eea/data/json/validated/0001AA7F-C601-424A-B2B8-BE6C9F5164E7.json\",    \n   }\n]\n</code></pre>"},{"location":"usage/nested/#implementation","title":"Implementation","text":""},{"location":"usage/nested/#modelization","title":"Modelization","text":"<p>In OpenCTI, all nested references and objects are modelized as relationships, to be able to pivot more easily on labels, external references, kill chain phases, marking definitions, etc.</p> <p></p>"},{"location":"usage/nested/#import-export","title":"Import &amp; export","text":"<p>When importing and exporting data to/from OpenCTI, the translation between nested references and objects to full-fledged nodes and edges is automated and therefore transparent for the users. Here is an example with the object in the graph above:</p> <pre><code>{\n   \"id\": \"file--b6be3f04-e50f-5220-af3a-86c2ca66b719\",\n   \"spec_version\": \"2.1\",\n   \"x_opencti_description\": \"...\",\n   \"x_opencti_score\": 50,\n   \"hashes\": {\n       \"MD5\": \"b502233b34256285140676109dcadde7\"\n   },\n   \"labels\": [\n       \"cookiecutter\",\n       \"clouddata-networks-1\"\n   ],\n   \"external_references\": [\n       {\n           \"source_name\": \"Sekoia.io\",\n           \"url\": \"https://app.sekoia.io/intelligence/objects/indicator--3e6d61b4-d5f0-48e0-b934-fdbe0d87ab0c\"\n       }\n   ],\n   \"x_opencti_id\": \"8a3d108f-908c-4833-8ff4-4d6fc996ce39\",\n   \"type\": \"file\",\n   \"created_by_ref\": \"identity--b5b8f9fc-d8bf-5f85-974e-66a7d6f8d4cb\",\n   \"object_marking_refs\": [\n       \"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9\"\n   ]\n}\n</code></pre>"},{"location":"usage/notifications/","title":"Notifications and alerting","text":"<p>In the evolving landscape of cybersecurity, timely awareness is crucial. OpenCTI empowers users to stay informed and act swiftly through its robust notifications and alerting system. This feature allows users to create personalized triggers that actively monitor the platform for specific events and notify them promptly when these conditions are met.</p> <p>From individual users tailoring their alert preferences to administrators orchestrating collaborative triggers for Groups or Organizations, OpenCTI's notification system is a versatile tool for keeping cybersecurity stakeholders in the loop.</p> <p>The main menu \"Notifications and triggers\" for creating and managing notifications is located in the top right-hand corner with the bell icon.</p> <p> </p>"},{"location":"usage/notifications/#triggers","title":"Triggers","text":"<p>In OpenCTI, triggers serve as personalized mechanisms for users to stay informed about specific events that align with their cybersecurity priorities. Users can create and manage triggers to tailor their notification experience. Each trigger operates by actively listening to events based on predefined filters and event types, promptly notifying users via chosen notifiers when conditions are met.</p> <p></p>"},{"location":"usage/notifications/#trigger-management","title":"Trigger management","text":"<p>Individual user triggers: Each user possesses the autonomy to craft their own triggers, finely tuned to their unique preferences and responsibilities. By setting up personalized filters and selecting preferred notifiers, users ensure that they receive timely and relevant notifications aligned with their specific focus areas.</p> <p>Administrative control: Platform administrators have the capability to create and manage triggers for Users, Groups and Organizations. This provides centralized control and the ability to configure triggers that address collective cybersecurity objectives. Users within the designated Group or Organization will benefit from triggers with read-only access rights. These triggers are to be created directly on the User|Group|Organization with whom to share them in \"Settings &gt; Security &gt; Users|Groups|Organizations\".</p> <p></p>"},{"location":"usage/notifications/#trigger-filters","title":"Trigger filters","text":"<p>Leveraging the filters, users can meticulously define the criteria that activate their triggers. This level of granularity ensures that triggers are accurate, responding precisely to events that matter most. Users can tailor filters to consider various parameters such as object types, markings, sources, or other contextual details. They can also allow notifications for the assignment of a Task, a Case, etc.</p> <p>Beyond filters, a trigger can be configured to respond to three event types: creation, modification, and deletion.</p> <p></p>"},{"location":"usage/notifications/#instance-triggers","title":"Instance triggers","text":"<p>Instance triggers offer a targeted approach to live monitoring by allowing users to set up triggers specific to one or several entities. These triggers, when activated, keep a vigilant eye on a predefined set of events related to the selected entities, ensuring that you stay instantly informed about crucial changes.</p>"},{"location":"usage/notifications/#creating-instance-triggers","title":"Creating instance triggers","text":"<p>Method 1: Using the general trigger creation form</p> <ol> <li>Go on the \"Notifications and triggers\" window.</li> <li>Navigate to the \"Triggers and digests\" tab.</li> <li>Access the general trigger creation form.</li> <li>Toggle the switch \"Instance trigger\".</li> <li>Choose the entities to monitor.</li> </ol> <p></p> <p>Method 2: Quick subscription</p> <ol> <li>On an entity's overview, locate the \"Instance trigger quick subscription\" button with the bell icon at the top right.</li> <li>Click on the button to create the instance trigger.</li> <li>(Optional) Click on it again to modify the instance trigger created.</li> </ol> <p></p>"},{"location":"usage/notifications/#events-monitored-by-instance-triggers","title":"Events monitored by instance triggers","text":"<p>An instance trigger set on an entity X actively monitors the following events:</p> <ul> <li>Update/Deletion of X: Stay informed when the selected entity undergoes changes or is deleted.</li> <li>Creation/Deletion of relationships: Receive notifications about relationships being added or removed from/to X.</li> <li>Creation/Deletion of related entities: Be alerted when entities that have X in its refs - i.e. contains X, is shared with X, is created by X, etc. - are created or deleted.</li> <li>Adding/Removing X in ref: Stay in the loop when X is included or excluded from the ref of other entities - i.e. adding X in the author of an entity, adding X in a report, etc.).</li> </ul> <p>Entity deletion notification</p> <p>It's important to note that the notification of entity deletion can occur in two scenarios:     - Real entity deletion: When the entity is genuinely deleted from the platform.     - Visibility loss: When a modification to the entity results in the user losing visibility for that entity.</p>"},{"location":"usage/notifications/#digest","title":"Digest","text":"<p>Digests provide an efficient way to streamline and organize your notifications. By grouping notifications based on selected triggers and specifying the delivery period (daily, weekly, monthly), you gain the flexibility to receive consolidated updates at your preferred time, as opposed to immediate notifications triggered by individual events.</p>"},{"location":"usage/notifications/#creating-digests","title":"Creating digests","text":"<ol> <li>Go on the \"Notifications and triggers\" window.</li> <li>Navigate to the \"Triggers and digests\" tab.</li> <li>Create a new digest.</li> <li>Configure digest: Set the parameters, including triggers to be included and the frequency of notifications (daily, weekly, monthly). </li> <li>Choose the notifier(s): Select the notification method(s) (e.g. within the OpenCTI interface, via email, etc.).</li> </ol>"},{"location":"usage/notifications/#benefits-of-digests","title":"Benefits of digests","text":"<ul> <li>Organized notifications: Digests enable you to organize and categorize notifications, preventing a flood of individual alerts.</li> <li>Customized delivery: Choose the frequency of digest delivery based on your preferences, whether it's a daily overview, a weekly summary, or a monthly roundup.</li> <li>Reduced distractions: Receive notifications at a scheduled time, minimizing interruptions and allowing you to focus on critical tasks.</li> </ul> <p>Digests enhance your control over notification management, ensuring a more structured and convenient approach to staying informed about important events.</p>"},{"location":"usage/notifications/#notifiers","title":"Notifiers","text":"<p>In OpenCTI, notifiers serve as the channels for delivering notifications, allowing users to stay informed about critical events. The platform offers two built-in notifiers, \"Default mailer\" for email notifications and \"User interface\" for in-platform alerts.</p> <p></p>"},{"location":"usage/notifications/#notifier-connectors","title":"Notifier connectors","text":"<p>OpenCTI features built-in notifier connectors that empower users to create personalized notifiers for notification and activity alerting. Three essential connectors are available:</p> <ul> <li>Platform mailer connector: Enables sending notifications directly within the OpenCTI platform.</li> <li>Simple mailer connector: Offers a straightforward approach to email notifications with simplified configuration options.</li> <li>Generic webhook connector: Facilitates communication through webhooks.</li> </ul> <p>OpenCTI provides two samples of webhook notifiers designed for Teams integration.</p> <p></p>"},{"location":"usage/notifications/#configuration-and-access","title":"Configuration and Access","text":"<p>Notifiers are manageable in the \"Settings &gt; Customization &gt; Notifiers\" window and can be restricted through Role-Based Access Control (RBAC). Administrators can restrict access to specific Users, Groups, or Organizations, ensuring controlled usage.</p> <p>For guidance on configuring custom notifiers and explore detailed setup instructions, refer to the dedicated documentation page.</p>"},{"location":"usage/overview/","title":"Overview","text":""},{"location":"usage/overview/#introduction","title":"Introduction","text":"<p>The following chapter aims at giving the reader a step-by-step description of what is available on the platform and the meaning of the different tabs and entries.</p> <p>When the user connects to the platform, the home page is the <code>Dashboard</code>. This <code>Dashboard</code> contains several visuals summarizing the types and quantity of data recently imported into the platform.</p> <p>Dashboard</p> <p>To get more information about the components of the default dashboard, you can consult the Getting started.</p> <p>The left side panel allows the user to navigate through different windows and access different views and categories of knowledge.</p> <p></p>"},{"location":"usage/overview/#structure","title":"Structure","text":""},{"location":"usage/overview/#the-hot-knowledge","title":"The \"hot knowledge\"","text":"<p>The first part of the platform in the left menu is dedicated to what we call the \"hot knowledge\", which means this is the entities and relationships which are added on a daily basis in the platform and which generally require work / analysis from the users.</p> <ul> <li><code>Analyses</code>: all containers which convey relevant knowledge such as reports, groupings and malware analyses.</li> <li><code>Cases</code>: all types of case like incident responses, requests for information, for takedown, etc.</li> <li><code>Events</code>: all incidents &amp; alerts coming from operational systems as well as sightings.</li> <li><code>Observations</code>: all technical data in the platform such as observables, artifacts and indicators.</li> </ul>"},{"location":"usage/overview/#the-cold-knowledge","title":"The \"cold knowledge\"","text":"<p>The second part of the platform in the left menu is dedicated to the \"cold knowledge\", which means this is the entities and relationships used in the hot knowledge. You can see this as the \"encyclopedia\" of all pieces of knowledge you need to get context: threats, countries, sectors, etc.</p> <ul> <li><code>Threats</code>: all threats entities from campaigns to threat actors, including intrusion sets.</li> <li><code>Arsenal</code>: all tools and pieces of malware used and/or targeted by threats, including vulnerabilities.</li> <li><code>Techniques</code>: all objects related to tactics and techniques used by threats (TTPs, etc.).</li> <li><code>Entities</code>: all non-geographical contextual information such as sectors, events, organizations, etc.</li> <li><code>Locations</code>: all geographical contextual information, from cities to regions, including precise positions.</li> </ul>"},{"location":"usage/overview/#hide-categories","title":"Hide categories","text":"<p>You can customize the experience in the platform by hiding some categories in the left menu, whether globally or for a specific role.</p>"},{"location":"usage/overview/#hide-categories-globally","title":"Hide categories globally","text":"<p>In the <code>Settings &gt; Parameters</code>, it is possible for the platform administrator to hide categories in the platform for all users.</p> <p></p>"},{"location":"usage/overview/#hide-categories-in-roles","title":"Hide categories in roles","text":"<p>In OpenCTI, the different roles are highly customizable. It is possible to defined default dashboards, triggers, etc. but also be able to hide categories in the roles:</p> <p></p>"},{"location":"usage/overview/#presentation-of-a-typical-page-in-opencti","title":"Presentation of a typical page in OpenCTI","text":"<p>While OpenCTI features numerous entities and tabs, many of them share similarities, with only minor differences arising from specific characteristics. These differences may involve the inclusion or exclusion of certain fields, depending on the nature of the entity.</p> <p>In this part will only be detailed a general outline of a \"typical\" OpenCTI page. The specifies of the different entities will be detailed in the corresponding pages below (Activities and Knowledge).</p> <p></p> <p></p>"},{"location":"usage/overview/#overview_1","title":"Overview","text":"<p>In the <code>Overview</code> tab on the entity, you will find all properties of the entity as well as the recent activities.</p> <p>First, you will find the <code>Details</code> section, where are displayed all properties specific to the type of entity you are looking at, an example below with a piece of malware:</p> <p></p> <p>Thus, in the <code>Basic information</code> section, are displayed all common properties to all objects in OpenCTI, such as the marking definition, the author, the labels (i.e. tags), etc.</p> <p></p> <p>Below these two sections, you will find latest modifications in the Knowledge base related to the Entity:</p> <ul> <li><code>Latest created relationships</code>: display the latest relationships that have been created from or to this Entity. For example, latest Indicators of Compromise and associated Threat Actor of a Malware.</li> <li><code>latest containers about the object</code>: display all the Cases and Analyses that contains this Entity. For example, the latest Reports about a Malware.</li> <li><code>External references</code>: display all the external sources associated with the Entity. You will often find here links to external reports or webpages from where Entity's information came from.</li> <li><code>History</code>: display the latest chronological modifications of the Entity and its relationships that occurred in the platform, in order to traceback any alteration.</li> </ul> <p> </p> <p>Last, all Notes written by users of the platform about this Entity are displayed in order to access unstructured analysis comments.</p> <p></p>"},{"location":"usage/overview/#knowledge","title":"Knowledge","text":"<p>In the <code>Knowledge</code> tab, which is the central part of the entity, you will find all the Knowledge related to the current entity. The <code>Knowledge</code> tab is different for Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) entities than for all the other entity types.</p> <ul> <li>The <code>Knowledge</code> tab of those entities (who represents Analyses or Cases that can contains a collection of Objects) is the place to integrate and link together entities. For more information on how to integrate information in OpenCTI using the knowledge tab of a report, please refer to the part Manual creation.</li> <li>The <code>Knowledge</code> tabs of any other entity (that does not aim to contain a collection of Objects) gather all the entities which have been at some point linked to the entity the user is looking at. For instance, as shown in the following capture, the <code>Knowledge</code> tab of Intrusion set APT29, gives access to the list of all entities APT29 is attributed to, all victims the intrusion set has targeted, all its campaigns, TTPs, malware etc. For entities to appear in these tabs under <code>Knowledge</code>, they need to have been linked to the entity directly or have been computed with the inference engine.</li> </ul> <p></p>"},{"location":"usage/overview/#focus-on-indicators-and-observables","title":"Focus on Indicators and Observables","text":"<p>The <code>Indicators</code> and <code>Observables</code> section offers 3 display modes: - The <code>entities view</code>, which displays the indicators/observables linked to the entity. - The <code>relationship view</code>, which displays the various relationships between the indicators/observables linked to the entity and the entity itself. - The <code>contextual view</code>, which displays the indicators/observables contained in the cases and analyses that contain the entity.</p> <p></p> <p></p>"},{"location":"usage/overview/#content","title":"Content","text":"<p>The <code>Content</code> tab allows for uploading and creating outcomes documents related to the content of the current entity (in PDF, text, HTML or markdown files). This specific tab enable to previzualize, manage and write deliverable associated with the entity. For example an analytic report to share with other teams, a markdown files to feed a collaborative wiki with, etc.</p> <p>The <code>Content</code> tab is available for a subset of entities: <code>Report</code>, <code>Incident</code>, <code>Incident response</code>, <code>Request for Information</code>, and <code>Request for Takedown</code>.</p> <p></p> <p></p>"},{"location":"usage/overview/#analyses","title":"Analyses","text":"<p>The <code>Analyses</code> tab contains the list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) in which the entity has been identified.</p> <p></p> <p>By default, this tab display the list, but you can also display the content of all the listed Analyses on a graph, allowing you to explore all their Knowledge and have a glance of the context around the Entity.</p> <p></p> <p></p>"},{"location":"usage/overview/#data","title":"Data","text":"<p>The <code>Data</code> tab contains documents that are associated to the object and were either:</p> <ul> <li>Uploaded to the platform : for instance the PDF document containing the text of the report</li> <li>Generated from the platform to be downloaded : a JSON or CSV file containing information on the object and generated by the user.</li> <li>associated to an external reference</li> </ul> <p>Analyst Workbench can also be created from here. They will contain the entity by default.</p> <p></p> <p>In addition, the <code>Data</code> tab of <code>Threat actors (group)</code>, <code>Threat actors (individual)</code>, <code>Intrusions sets</code>, <code>Organizations</code>, <code>Individuals</code> have an extra panel:</p> <ul> <li>Pictures Management: allows to manage the profile pictures attached to the entity.</li> </ul> <p> </p> <p></p>"},{"location":"usage/overview/#history","title":"History","text":"<p>The <code>History</code> tab displays the history of change of the Entity, update of attributes, creation of relations, ...</p> <p>Because of the volumes of information the history is written in a specific index that consume the redis stream to rebuild the history for the UI. </p>"},{"location":"usage/overview/#less-frequent-tabs","title":"Less frequent tabs","text":"<ul> <li>The <code>Observables</code> tab (for Reports and Observed data): A table containing all SCO (Stix Cyber Observable) contained in the Report or the Observed data, with search and filters available. It also displays if the SCO has been added directly or through inferences with the reasoning engine</li> <li>the <code>Entities</code> tab (for Reports and Observed data): A table containing all SDO (Stix Domain Objects) contained in the Report or the Observed data, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables:</li> <li>the <code>Sightings</code> tab (for Indicators and Observables): A table containing all <code>Sightings</code> relationships corresponding to events in which <code>Indicators</code> (IP, domain name, URL, etc.) are detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or EDR.</li> </ul>"},{"location":"usage/pivoting/","title":"Pivot and investigate","text":"<p>In OpenCTI, all data are structured as an extensive knowledge graph, where every element is interconnected. The investigation functionality provides a powerful tool for pivoting on any entity or relationship within the platform. Pivoting enables users to explore and analyze connections between entities and relationships, facilitating a comprehensive understanding of the data.</p> <p>To access investigations, navigate to the top right corner of the toolbar:</p> <p></p> <p>Access restriction</p> <p>When an investigation is created, it is initially visible only to the creator, allowing them to work on the investigation before deciding to share it. The sharing mechanism is akin to that of dashboards. For further details, refer to the Access control section in the dashboard documentation page.</p>"},{"location":"usage/pivoting/#perform-investigation","title":"Perform investigation","text":""},{"location":"usage/pivoting/#manipulate-entity","title":"Manipulate entity","text":"<p>We can add any existing entity of the platform to your investigation.</p> <p></p> <p>After adding an entity, we can choose the entity and view its details in the panel that appears on the right of the screen.</p> <p>On each node, we'll notice a bullet with a number inside, serving as a visual indication of how many entities are linked to it but not currently displayed in the graph. Keep in mind that this number is an approximation, which is why there's a \"+\" next to it. If there's no bullet displayed, it means there's nothing to expand from this node.</p> <p></p>"},{"location":"usage/pivoting/#expansion","title":"Expansion","text":"<p>To incorporate these linked entities into the graph, we just have to expand the nodes. Utilize the button with a 4-arrows logo in the mentioned menu, or double-click on the entity directly. This action opens a new window where we can choose the types of entities and relationships we wish to expand.</p> <p></p> <p>For instance, in the image above, selecting the target Malware and the relationship Uses implies expanding in my investigation graph all Malware linked to this node with a relationship of type Uses.</p>"},{"location":"usage/pivoting/#roll-back-expansion","title":"Roll back expansion","text":"<p>Expanding a graph can add a lot of entities and relations, making it not only difficult to read but sometimes counterproductive since it brings entities and relations that are not useful to your investigations. To solve this problem, there is a button to undo the last expansion.</p> <p>When clicking on this button, we will retrieve the state in which your graph was before your expansion. As a result, please note that all add or remove actions made since the last expansion will be lost: in other words, if you have expanded your graph, and then have added some entities in your graph, when clicking on rollback button, the entities that you have added will not be in your graph.</p> <p></p> <p>You can roll back your investigation graph up to the last 10 expand actions.</p>"},{"location":"usage/pivoting/#manipulate-relationship","title":"Manipulate relationship","text":"<p>We can create a relationship between entities directly within our investigation. To achieve this, select multiple entities by clicking on them while holding down the shift key. Subsequently, a button appears at the bottom right to create one (or more, depending on the number of entities selected) relationships.</p> <p></p> <p>Relationship creation</p> <p>Creating a relationship in the investigation graph will generate the relationship in your knowledge base.</p>"},{"location":"usage/pivoting/#capitalize-on-an-investigation","title":"Capitalize on an investigation","text":""},{"location":"usage/pivoting/#export-investigation","title":"Export investigation","text":"<p>Users have the capability to export investigations, providing a way to share, document, or archive their findings.</p> <ul> <li>PDF and image formats: Users can export investigations in either PDF or image format, offering flexibility in sharing and documentation.</li> <li>STIX bundle: The platform allows the export of the entire content of an investigation graph as a STIX bundle. In the STIX format, all objects within the investigation graph are automatically aggregated into a Report object.</li> </ul> <p></p>"},{"location":"usage/pivoting/#turn-investigation-into-a-container","title":"Turn investigation into a container","text":"<p>Users can efficiently collect and consolidate the findings of an investigation by adding the content into dedicated containers. The contents of an investigation can be imported into various types of containers, including:</p> <ul> <li>Grouping</li> <li>Incident Response</li> <li>Report</li> <li>Request for Information</li> <li>Request for Takedown</li> </ul> <p></p> <p>We have the flexibility to choose between creating a new container on the fly or adding investigation content to an existing container. </p> <p></p> <p></p> <p>After clicking on the <code>ADD</code> button, the browser will redirect to the Knowledge tab of the container where we added the content of our investigation. If we added it to multiple containers, the redirection will be to the first of the list.</p> <p></p>"},{"location":"usage/reliability-confidence/","title":"Reliability and Confidence","text":""},{"location":"usage/reliability-confidence/#generalities","title":"Generalities","text":"<p>In (Cyber) Threat Intelligence, evaluation of information sources and of information quality is one of the most important aspect of the work. It is of the utter most importance to assess situations by taking into account reliability of the sources and credibility of the information.</p> <p>This concept is foundational in OpenCTI, and have real impact on:</p> <ul> <li>the data deduplication process</li> <li>the data stream filtering for ingestion and sharing</li> </ul>"},{"location":"usage/reliability-confidence/#what-is-the-reliability-of-a-source","title":"What is the Reliability of a source?","text":"<p>Reliability of a source of information is a measurement of the trust that the analyst can have about the source, based on the technical capabilities or history of the source. Is the source a reliable partner with long sharing history? A competitor? Unknown?</p> <p>Reliability of sources are often stated at organizational level, as it requires an overview of the whole history with it. </p> <p>In the Intelligence field, Reliability is often notated with the NATO Admiralty code.</p>"},{"location":"usage/reliability-confidence/#what-is-confidence-of-an-information","title":"What is Confidence of an information?","text":"<p>Reliability of a source is important but even a trusted source can be wrong. Information in itself has a credibility, based on what is known about the subject and the level of corroboration by other sources.</p> <p>Credibility is often stated at the analyst team level, expert of the subject, able to judge the information with its context.</p> <p>In the Intelligence field, Confidence is often notated with the NATO Admiralty code.</p> <p>Why Confidence instead of Credibility?</p> <p>Using both Reliability and Credibility is an advanced use case for most of CTI teams. It requires a mature organization and a well staffed team. For most of internal CTI team, a simple confidence level is enough to forge assessment, in particular for teams that concentrate on technical CTI. </p> <p>Thus in OpenCTI, we have made the choice to fuse the notion of Credibility with the Confidence level that is commonly used by the majority of users. They have now the liberty to push forward their practice and use both Confidence and Reliability in their daily assessments.</p>"},{"location":"usage/reliability-confidence/#reliability-open-vocabulary","title":"Reliability open vocabulary","text":"<p>Reliability value can be set for every Entity in the platform that can be Author of Knowledge:</p> <ul> <li><code>Organizations</code></li> <li><code>Individuals</code></li> <li><code>Systems</code></li> <li>and also <code>Reports</code></li> </ul> <p>Reliability on <code>Reports</code> allows you to specify the reliability associated to the original author of the report if you received it through a provider.</p> <p>For all Knowledge in the platform, the reliability of the source of the Knowledge (author) is displayed in the Overview. This way, you can always forge your assessment of the provided Knowledge regarding the reliability of the author.</p> <p></p> <p>You can also now filter entities by the reliability of its author.</p> <p>Tip</p> <p>This way, you may choose to feed your work with only Knowledge provided by reliable sources.</p> <p>Reliability is an open vocabulary that can be customized in Settings -&gt; Taxonomies -&gt; Vocabularies : reliability_ov. </p> <p>Info</p> <p>The setting by default is the Reliability scale from NATO Admiralty code. But you can define whatever best fit your organization.</p> <p></p>"},{"location":"usage/reliability-confidence/#confidence-scale","title":"Confidence scale","text":"<p>Confidence level can be set for:</p> <ul> <li>Analyses: <code>Report</code>, <code>Grouping</code>, <code>Malware analysis</code>, <code>Notes</code></li> <li>Cases: <code>Incident Response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>, <code>Feedback</code></li> <li>Events: <code>Incident</code>, <code>Sighting</code>, <code>Observed data</code></li> <li>Observations: <code>Indicator</code>, <code>Infrastructure</code></li> <li>Threats: <code>Threat actor (Group)</code>, <code>Threat actor (Individual)</code>, <code>Intrusion Set</code>, <code>Campaign</code></li> <li>Arsenal: <code>Malware</code>, <code>Channel</code>, <code>Tool</code>, <code>Vulnerability</code></li> </ul> <p>For all of these entities, the Confidence level is displayed in the Overview, along with the Reliability. This way, you can rapidly assess the Knowledge with the Confidence level representing the credibility/quality of the information.</p>"},{"location":"usage/reliability-confidence/#confidence-scale-customization","title":"Confidence scale customization","text":"<p>Confidence level is a numerical value between 0 and 100. But Multiple \"Ticks\" can be defined and labelled to provide a meaningful scale.</p> <p>Confidence level can be customized for each entity type in Settings &gt; Customization &gt; Entity type.</p> <p></p> <p>As such customization can be cumbersome, three confidence level templates are provided in OpenCTI:</p> <ul> <li>Admiralty: corresponding to the Admiralty code's credibility scale</li> <li>Objective: corresponding to a full objective scale, aiming to leave any subjectivity behind. With this scale, an information confidence is:<ul> <li>\"Cannot be judged\": there is no data regarding the credibility of the information</li> <li>\"Told\": the information is known because it has been told to the source. The source doesn't verify it by any means.</li> <li>\"Induced\": the information is the result of an analysis work and is based on other similar information assumed to be true.</li> <li>\"Deduced\": the information is the result of an analysis work, and is a logical conclusion of other information assumed to be true.</li> <li>\"Witnessed\": the source have observed itself the described situation or object.</li> </ul> </li> <li>standard: the historic confidence level scale in OpenCTI defining a Low, Med and High level of confidence.</li> </ul> <p>It is always possible to modify an existing template to define a custom scale adapted to your context.</p> <p>Tip</p> <p>If you use the Admiralty code setting for both reliability and Confidence, you will find yourself with the equivalent of NATO confidence notation in the Overview of your different entities (A1, B2, C3, etc.)</p> <p></p>"},{"location":"usage/reliability-confidence/#max-confidence-level","title":"Max confidence level","text":""},{"location":"usage/reliability-confidence/#overview","title":"Overview","text":"<p>We know that in organizations, different users do not always have the same expertise or seniority.  As a result, some specific users can be more \"trusted\" when creating or updating knowledge than others. Additionally, because connectors, TAXII feeds and streams are all linked to respectively one user, it is important to be able to differentiate which connector, stream or TAXII feed is more trustable than others.</p> <p>This is why we have introduced the concept of max confidence level to tackle this use case.</p> <p>Max confidence level per user allows organizations to fine tune their users to ensure knowledge updated and created stays as consistent as possible.</p>"},{"location":"usage/reliability-confidence/#overall-way-of-working","title":"Overall way of working","text":"<p>The overall idea is that users with a max confidence level lower than a confidence level of an entity cannot update or delete this entity.</p> <p>Also, in a conservative approach, when 2 confidence levels are possible, we would always take the lowest one.</p> <p>To have a detailed understanding of the concept, please browse through this diagram:</p>"},{"location":"usage/reliability-confidence/#how-to-set-a-confidence-level","title":"How to set a confidence level","text":"<p>To see how to set up the confidence level, please go in this page.</p>"},{"location":"usage/reliability-confidence/#usage-in-opencti","title":"Usage in OpenCTI","text":""},{"location":"usage/reliability-confidence/#example-with-the-admiralty-code-template","title":"Example with the admiralty code template","text":"<p>Your organization have received a report from a CTI provider. At your organization level, this provider is considered as reliable most of the time and its reliability level has been set to \"B - Usually Reliable\" (your organization uses the Admiralty code).</p> <p>This report concerns ransomware threat landscape and have been analysed by your CTI analyst specialized in cybercrime. This analyst has granted a confidence level of \"2 - Probably True\" to the information. </p> <p>As a technical analyst, through the cumulated reliability and Confidence notations, you now know that the technical elements of this report are probably worth consideration.</p> <p></p>"},{"location":"usage/reliability-confidence/#example-with-the-objective-template","title":"Example with the Objective template","text":"<p>As a CTI analyst in a governmental CSIRT, you build up Knowledge that will be shared within the platform to beneficiaries. Your CSIRT is considered as a reliable source by your beneficiaries, even if you play a role of a proxy with other sources, but your beneficiaries need some insights about how the Knowledge has been built/gathered. </p> <p>For that, you use the \"Objective\" confidence scale in your platform to provide beneficiaries with that. When the Knowledge is the work of the investigation of your CSIRT, either from incident response or attack infrastructure investigation, you set the confidence level to \"Witnessed\", \"Deduced\" or \"Induced\" (depending on if you observed directly the data, or inferred it during your research). When the information has not been verified by the CSIRT but has value to be shared with beneficiaries, you can use the \"Told\" level to make it clear to them that the information is probably valuable but has not been verified.</p> <p></p>"},{"location":"usage/search/","title":"Search for knowledge","text":"<p>In OpenCTI, you have access to different capabilities to be able to search for knowledge in the platform. In most cases, a search by keyword can be refined with additional filters for instance on the type of object, the author etc.</p>"},{"location":"usage/search/#global-search","title":"Global search","text":"<p>The global search is always available in the top bar of the platform.</p> <p></p> <p>This search covers all STIX Domain Objects (SDOs) and STIX Cyber Observables (SCOs) in the platform. The search results are sorted according to the following behaviour:</p> <ul> <li>Priority 1 for exact matching of the keyword in one attribute of the objects.</li> <li>Priority 2 for partial matching of the keyword in the <code>name</code>, the <code>aliases</code> and the <code>description</code> attributes (full text search).</li> <li>Priority 3 for partial matching of the keyword in all other attributes (full text search).</li> </ul> <p>If you get unexpected result, it is always possible to add some filters after the initial search:</p> <p></p> <p>Also, using the <code>Advanced search</code> button, it is possible to directly put filters in a global search:</p> <p></p> <p>Advanced filters</p> <p>You have access to advanced filters all accross the UI, if you want to know more about how to use these  filters with the API or the Python library, don't hesitate to read the dedicated page</p>"},{"location":"usage/search/#full-text-search-in-files-content","title":"Full text search in files content","text":"<p>Enterprise edition</p> <p>Full text search in files content is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p> <p>It's possible to extend the global search by keywords to the content of documents uploaded to the platform via the Data import tab, or directly linked to an entity via its Data tab.</p> <p>It is particularly useful to enable <code>Full text indexing</code> to avoid missing important information that may not have been structured within the platform. This situation can arise due to a partial automatic import of document content, limitations of a connector, and, of course, errors during manual processing.</p> <p></p> <p>In order to search in files, you need to configure file indexing.</p>"},{"location":"usage/search/#bulk-search","title":"Bulk search","text":"<p>The bulk search capabilities is available in the top bar of the platform and allows you to copy paste a list of keyword or objects (ie. list of domains, list of IP addresses, list of vulnerabilities, etc.) to search in the platform:</p> <p></p> <p>When searching in bulk, OpenCTI is only looking for an exact match in some properties:</p> <ul> <li><code>name</code></li> <li><code>aliases</code></li> <li><code>x_opencti_aliases</code></li> <li><code>x_mitre_id</code></li> <li><code>value</code></li> <li><code>subject</code></li> <li><code>abstract</code></li> <li><code>hashes.MD5</code></li> <li><code>hashes.SHA-1</code></li> <li><code>hashes.SHA-256</code></li> <li><code>hashes.SHA-512</code></li> <li><code>x_opencti_additional_names</code></li> </ul> <p>When something is not found, it appears in the list as <code>Unknown</code> and will be excluded if you choose to export your search result in a JSON STIX bundle or in a CSV file.</p> <p></p>"},{"location":"usage/search/#contextual-search","title":"Contextual search","text":"<p>In most of the screens of knowledge, you always have a contextual search bar allowing you to filter the list you are on:</p> <p></p> <p>The search keyword used here is taken into account if you decide to export the current view in a file such as a JSON STIX bundle or a CSV file.</p>"},{"location":"usage/search/#other-search-bars","title":"Other search bars","text":"<p>Some other screens can contain search bars for specific purposes. For instance, in the graph views to filter the nodes displayed on the graph:</p> <p></p>"},{"location":"usage/tips-widget-creation/","title":"Pro-tips on widget creation","text":"<p>Previously, the creation of widgets has been covered. To help users being more confident in creating widgets, here are some details to master the widget creation.</p> <p></p>"},{"location":"usage/tips-widget-creation/#how-to-choose-the-appropriate-widget-visualization-for-your-use-case","title":"How to choose the appropriate widget visualization for your use case?","text":"<p>We can classify the widgets in 3 different types.</p>"},{"location":"usage/tips-widget-creation/#single-dimension-widgets","title":"Single dimension widgets","text":"<p>Use these widgets when you would like to display information about one single type of object (entity or relation).</p> <ul> <li>Widget visualizations: number, list, list (distribution), timeline, donuts, radar, map, bookmark, tree map.</li> <li>Use case example: view the amount of malware in platform (number widget), view the top 10 threat actor group target a specific country (distribution list widget), etc.</li> </ul>"},{"location":"usage/tips-widget-creation/#multi-dimension-widgets","title":"Multi dimension widgets","text":"<p>Use these widgets if you would like to compare or have some insights about similar types of object (up to 5).</p> <ul> <li>Widget visualizations: line, area, heatmap, vertical bars.</li> <li>Use case example: view the amount of malware, intrusion sets, threat actor groups added in the course of last month in the platform (line or area widget).</li> </ul> <p>Type of object in widget</p> <p>These widgets need to use the same \"type\" of object to work properly. You always need to add relationships in the filter view if you have selected a \"knowledge graph\" perspective. If you have selected the knowledge graph entity, adding \"Entities\" (click on <code>+ entities</code>) will not work, since you are not counting the same things.</p>"},{"location":"usage/tips-widget-creation/#break-down-widgets","title":"Break down widgets","text":"<p>Use this widget if you want to divide your data set into smaller parts to make it clearer and more useful for analysis.</p> <ul> <li>Widget visualization: horizontal bars.</li> <li>Use case example: view the list of malware targeting a country breakdown by the type of malware.</li> </ul> <p></p>"},{"location":"usage/tips-widget-creation/#adding-datasets-to-your-widget","title":"Adding datasets to your widget","text":"<p>Adding datasets can serve two purposes: comparing data or breakdown a view to have deeper understanding on what a specific dataset is composed of. </p>"},{"location":"usage/tips-widget-creation/#use-case-1-compare-several-datasets","title":"Use Case 1: compare several datasets","text":"<p>As mentioned in How to choose the appropriate widget visualization for your use case? section you can add data sets to compare different data. Make sure to add the same type of objects (entities or relations) to be able to compare the same objects, by using access buttons like <code>+</code>, <code>+ Relationships</code>, or <code>+ Entities</code>.</p> <p>You can add up to 5 different data sets.  The <code>Label</code> field allows you to name a data set, and this label can then be shown as a legend in the widget using the <code>Display legend</code> button in the widget parameters (see the next section).</p>"},{"location":"usage/tips-widget-creation/#use-case-2-break-down-your-chart","title":"Use case 2: break down your chart","text":"<p>As mentioned in How to choose the appropriate widget visualization for your use case? section you can add data sets to decompose your graph into smaller meaningful chunks. In the below points, you can find some use cases that will help you understand how to structure your data.</p> <p>You can break down a view either by entity or by relations, depending on what you need to count.</p>"},{"location":"usage/tips-widget-creation/#break-down-by-entity","title":"Break down by entity","text":"<p>Use case example: I need to understand what are the most targeted countries by malware, and have a breakdown for each country by malware type.</p> <p>Process:</p> <ol> <li>To achieve this use case, you first need to select the horizontal bar vizualisation.</li> <li>Then you need to select the knowledge graph perspective.</li> </ol> <p>In the filters view:</p> <ol> <li>Then input your main query <code>Source type = Malware AND Target type = Countries AND Relation type = Targets</code>. Add a label to your dataset. </li> <li>Add an entity data set by using access button <code>+ Entities</code>.</li> <li>Add the following filters <code>Entity type = Malware AND In regards of = targets</code>. Add a label to your dataset.</li> </ol> <p></p> <p>In the parameter view:</p> <ol> <li>Attribute (of your relation) = entity (so that you display the different entities values)</li> <li>Display the source toggle = off</li> <li>Attribute (of your entity malware) = Malware type (since you want to break down your relations by the malware types)</li> </ol> <p></p> <p>As a result, you get a list of countries broken down by malware types.</p> <p></p>"},{"location":"usage/tips-widget-creation/#break-down-by-relation","title":"Break down by relation","text":"<p>Use case example: I need to understand what are the top targeting malware and have a breakdown of the top targets per malware</p> <p>Process:</p> <ol> <li>To achieve this use case, you first need to select the horizontal bar vizualisation.</li> <li>Then you need to select the knowledge graph perspective.</li> </ol> <p>In the filters view:</p> <ol> <li>Then input your main query <code>Source type = Malware AND Relation type = Targets</code>. Add a label to your dataset. </li> <li>Add a relation data set by using access button  <code>+ Relationships</code></li> <li>Add the following filters <code>Source type = Malware AND Relation type = targets</code>. Add a label to your dataset.</li> </ol> <p></p> <p>In the parameter view:</p> <ol> <li>Attribute (of your relation): entity (so that you display the different entities values)</li> <li>Display the source toggle = on</li> <li>Attribute (of your entity malware) = Malware type (since you want to break down your relations by the malware types)</li> <li>Display the source toggle = off</li> </ol> <p></p> <p>As a result, you get a list of malware with the breakdown of their top targets.</p> <p></p>"},{"location":"usage/tips-widget-creation/#more-use-cases","title":"More use cases","text":"<p>To see more use cases, feel free to have a look at this blog post that will provide you additional information.</p>"},{"location":"usage/widgets/","title":"Widget creation","text":"<p>Creating widgets on the dashboard involves a four-step configuration process. By navigating through these configuration steps, users can design widgets that meet their specific requirements.</p>"},{"location":"usage/widgets/#widget-configuration","title":"Widget configuration","text":""},{"location":"usage/widgets/#1-visualization","title":"1. Visualization","text":"<p>Users can select from 15 diverse visualization options to highlight different aspects of their data. This includes simple views like counters and lists, as well as more intricate views like heatmaps and trees. The chosen visualization impacts the available perspectives and parameters, making it crucial to align the view with the desired data observations. Here are a few insights:</p> <ul> <li>Line and Area views: Ideal for visualizing activity volumes over time.</li> <li>Horizontal bar views: Designed to identify top entities that best satisfy applied filters (e.g., top malware targeting the Finance sector).</li> <li>Tree views: Useful for comparing activity volumes.</li> <li>...</li> </ul> <p></p>"},{"location":"usage/widgets/#2-perspective","title":"2. Perspective","text":"<p>A perspective is the way the platform will count the data to display in your widgets:</p> <ul> <li>Entities Perspective: Focuses on entities, allowing observation of simple knowledge based on defined filters and criteria. The count will be based on entities only.</li> <li>Knowledge Graph Perspective: Concentrates on relationships, displaying intricate knowledge derived from relationships between entities and specified filters.  The count will be based on relations only.</li> <li>Activity &amp; History Perspective: Centers on activities within the platform, not the knowledge content. This perspective is valuable for monitoring user and connector activities, evaluating data sources, and more.</li> </ul> <p></p>"},{"location":"usage/widgets/#3-filters","title":"3. Filters","text":""},{"location":"usage/widgets/#generic-knowledge","title":"Generic knowledge","text":"<p>Filters vary based on the selected perspective, defining the dataset to be utilized in the widget. Filters are instrumental in narrowing down the scope of data for a more focused analysis.</p> <p>While filters in the \"Entities\" and \"Activity &amp; History\" perspectives align with the platform's familiar search and feed creation filters, the \"Knowledge Graph\" perspective introduces a more intricate filter configuration.Therefore, they need to be addressed in more detail.</p>"},{"location":"usage/widgets/#filter-in-the-context-of-knowledge-graph","title":"Filter in the context of Knowledge Graph","text":"<p>Two types of filters are available in the Knowledge Graph perspective:</p> <ul> <li> <p>Main query filter</p> <ul> <li>Classic filters (gray): Define the relationships to be retrieved, forming the basis on which the widget displays data. Remember, statistics in the Knowledge Graph perspective are based on relationships.</li> </ul> </li> <li> <p>Pre-query filters</p> <ul> <li>Pre-query filters are used to provide to your main query a specific dataset. In other words, instead of making a query on the whole data set of your platform, you can already target a subset of data that will match certain criteria. They are two types of pre-query filters:<ul> <li>Dynamic filters on the source (orange): Refine data by filtering on entities positioned as the source (in the \"from\" position) of the relationship.</li> <li>Dynamic filters on the target (green): Refine data by filtering on entities positioned as the target (in the \"to\" position) of the relationship.</li> </ul> </li> </ul> </li> </ul> <p>Pre-query limitation</p> <p>The pre-query is limited to 5000 results. If your pre-query results in having more than 5000 results, your widget will only display statistics based on these 5000 results matching your pre-query, resulting in a wrong view. To avoid this issue, be specific in your pre-query filters.</p> <p>Example scenario:</p> <p>Let's consider an example scenario: Analyzing the initial access attack patterns used by intrusion sets targeting the finance sector.</p> <ol> <li>Classic filters: Define the relationships associated with the use of attack patterns by intrusion sets</li> <li>Dynamic filters on the source (Orange): Narrow down the data by filtering on intrusion sets targeting the finance sector.</li> <li>Dynamic filters on the target (Green): Narrow down the data by filtering on attack patterns associated with the kill chain's initial access phase.</li> </ol> <p>By leveraging these advanced filters, users can conduct detailed analyses within the Knowledge Graph perspective, unlocking insights that are crucial for understanding intricate relationships and statistics.</p> <p></p> <p>In certain views, you can access buttons like <code>+</code>, <code>+ Relationships,</code> or <code>+ Entities</code>. These buttons enable you to incorporate different data into the same widget for comparative analysis. For instance, in a Line view, adding a second set of filters will display two curves in the widget, each corresponding to one of the filtered data sets. Depending on the view, you can work with 1 to 5 sets of filters. The <code>Label</code> field allows you to name a data set, and this label can then be shown as a legend in the widget using the <code>Display legend</code> button in the widget parameters (see the next section).</p> <p></p>"},{"location":"usage/widgets/#4-parameters","title":"4. Parameters","text":"<p>Parameters depend on the chosen visualization and allow users to define widget titles, choose displayed elements from the filtered data, select data reference date, and configure various other parameters specific to each visualization.</p> <p>For the \"Knowledge Graph\" perspective, a critical parameter is the <code>Display the source</code> toggle. This feature empowers users to choose whether the widget displays entities from the source side or the target side of the relationships.</p> <ul> <li>Toggle ON (\"Display the source\"): The widget focuses on entities positioned as the source of the relationships (in the \"from\" position).</li> <li>Toggle OFF (\"Display the target\"): The widget shifts its focus to entities positioned as the target of the relationships (in the \"to\" position).</li> </ul> <p>This level of control ensures that your dashboard aligns precisely with your analytical objectives, offering a tailored perspective based on your data and relationship.</p> <p></p>"},{"location":"usage/widgets/#prerequisite-knowledge","title":"Prerequisite knowledge","text":"<p>To successfully configure widgets in OpenCTI, having a solid understanding of the platform's data modeling is essential. Knowing specific relationships, entities, and their attributes helps refine filters accurately. Let's explore two examples.</p> <p>Scenarios 1:</p> <p>Consider the scenario where you aim to visualize relationships between intrusion sets and attack patterns. In this case, the relevant relationship type connecting intrusion sets to attack patterns is labeled as \"Uses\" (as illustrated in the \"Filters\" section).</p> <p>Scenarios 2:</p> <p>Suppose your goal is to retrieve all reports associated with the finance sector. In this case, it's essential to use the correct filter for the finance sector. Instead of placing the finance sector in the \"Related entity\" filter, it should be placed in the \"Contains\" filter. Since a Report is a container object (like Cases and Groupings), it contains entities within it and is not related to entities.</p>"},{"location":"usage/widgets/#key-data-modeling-aspects","title":"Key data modeling aspects","text":"<ul> <li>Entities: Recognizing container (e.g. Reports, Cases and Groupings) and understanding the difference with non-container.</li> <li>Relationships: Identifying the relationship types connecting entities.</li> <li>Attributes: Understanding entities and relationships attributes for effective filtering.</li> </ul> <p>Having this prerequisite knowledge allows you to navigate the widget configuration process seamlessly, ensuring accurate and insightful visualizations based on your specific data requirements.</p>"},{"location":"usage/workbench/","title":"Analyst workbench","text":"<p>Workbenches serve as dedicated workspaces for manipulating data before it is officially imported into the platform. </p>"},{"location":"usage/workbench/#location-of-use","title":"Location of use","text":"<p>The workbenches are located at various places within the platform:</p>"},{"location":"usage/workbench/#data-import-and-analyst-workbenches-window","title":"Data import and analyst workbenches window","text":"<p>This window encompasses all the necessary tools for importing a file. Files imported through this interface will subsequently be processed by the import connectors, resulting in the creation of workbenches. Additionally, analysts can manually create a workbench by clicking on the \"+\" icon at the bottom right of the window.</p> <p></p>"},{"location":"usage/workbench/#data-tabs-of-all-entities","title":"Data tabs of all entities","text":"<p>Workbenches are also accessible through the \"Data\" tabs of entities, providing convenient access to import data associated with the entity.</p> <p></p>"},{"location":"usage/workbench/#operation","title":"Operation","text":"<p>Workbenches are automatically generated upon the import of a file through an import connector. When an import connector is initiated, it scans files for recognizable entities and subsequently creates a workbench. All identified entities are placed within this workbench for analyst reviews. Alternatively, analysts have the option to manually create a workbench by clicking on the \"+\" icon at the bottom right of the \"Data import and analyst workbenches\" window.</p> <p></p> <p>The workbench being a draft space, the analysts use it to review connector proposals before finalizing them for import. Within the workbench, analysts have the flexibility to add, delete, or modify entities to meet specific requirements.</p> <p></p> <p>Once the content within the workbench is deemed acceptable, the analyst must initiate the ingestion process by clicking on <code>Validate this workbench</code>. This action signifies writing the data in the knowledge base.</p> <p>Workbenches are drafting spaces</p> <p>Until the workbench is validated, the contained data remains in draft form and is not recorded in the knowledge base. This ensures that only reviewed and approved data is officially integrated into the platform.</p> <p>For more information on importing files, refer to the Import from files documentation page.</p> <p>Confidence level of created knowledge through workbench</p> <p>The confidence level of knowledge created through workbench is affected by the confidence level of the user. Please navigate to this page to understand in more details.</p>"},{"location":"usage/workflows/","title":"Workflows and assignation","text":"<p>Efficiently manage and organize your work within the OpenCTI platform by leveraging workflows and assignment. These capabilities provide a structured approach to tracking the status of objects and assigning responsibilities to users.</p>"},{"location":"usage/workflows/#workflows","title":"Workflows","text":"<p>Workflows are designed to trace the status of objects in the system. They are represented by the \"Processing status\" field embedded in each object. By default, this field is disabled for most objects but can be activated through the platform settings. For details on activating and configuring workflows, refer to the dedicated documentation page.</p> <p>Enabling workflows enhances visibility into the progress and status of different objects, providing a comprehensive view for effective management.</p> <p></p>"},{"location":"usage/workflows/#assignment-attributes","title":"Assignment attributes","text":"<p>Certain objects, including Reports, Cases, and Tasks, come equipped with \"Assignees\" and \"Participants\" attributes. These attributes serve the purpose of designating individuals responsible for the object and those who actively participate in it.</p> <p>Attributes can be set as mandatory or with default values, streamlining the assignment process. Users can also be assigned or designated as participants manually, contributing to a collaborative and organized workflow. For details on configuring attributes, refer to the dedicated documentation page.</p> <p></p> <p>Users can stay informed about assignments through notification triggers. By setting up notification triggers, users receive alerts when an object is assigned to them. This ensures timely communication and proactive engagement with assigned tasks or responsibilities.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"OpenCTI Documentation Space","text":"<p>Welcome to the OpenCTI Documentation space. Here you will be able to find all documents, meeting notes and presentations about the platform.</p> <p>Release notes</p> <p>Please, be sure to also take a look at the OpenCTI releases notes, they may contain important information about releases and deployments.</p>"},{"location":"#introduction","title":"Introduction","text":"<p>OpenCTI is an open source platform allowing organizations to manage their cyber threat intelligence knowledge and observables. It has been created in order to structure, store, organize and visualize technical and non-technical information about cyber threats.</p>"},{"location":"#getting-started","title":"Getting started","text":"<ul> <li> <p> Deployment &amp; Setup</p> <p>Learn how to deploy and configure the platform as well as launch connectors to get the first data in OpenCTI.</p> <p> Deploy now</p> </li> <li> <p> User Guide</p> <p>Understand how to use the platform, explore the knowledge, import and export information, create dashboard, etc.</p> <p> Explore</p> </li> <li> <p> Administration</p> <p>Know how to administrate OpenCTI, create users and groups using RBAC / segregation, put retention policies and custom taxonomies.</p> <p> Customize</p> </li> </ul> <p>Need more help?</p> <p>We are doing our best to keep this documentation complete, accurate and up to date. </p> <p>If you still have questions or you find something which is not sufficiently explained, join the Filigran Community on Slack.</p>"},{"location":"#latest-blog-posts","title":"Latest blog posts","text":"<p>All tutorials are published directly on the Medium blog, this section provides a comprehensive list of the most important ones.</p> <ul> <li> <p>Introducing decay rules implementation for Indicators in OpenCTI <sub><sup>Mar 25, 2024</sup></sub></p> <p>Cyber Threat Intelligence is made to be used. To be useful, it must be relevant and on time. It is why managing the lifecycle of Indicators of Compromise...</p> <p> Read</p> </li> <li> <p>Introducing advanced filtering possibilities in OpenCTI <sub><sup>Feb 5, 2024</sup></sub></p> <p>CTI databases are usually vast and made of complex, inter-dependent objects ingested from various sources. In this challenging context, cyber analysts need...</p> <p> Read</p> </li> <li> <p>Breaking change: evolution of the way Connector, Streams and Feeds import data in OpenCTI <sub><sup>Jan 29, 2024</sup></sub></p> <p>How Connectors, Feeds and Streams use Confidence level currently...</p> <p> Read</p> </li> </ul>"},{"location":"#additional-resources","title":"Additional resources","text":"<p>Below, you will find external resources which may be useful along your OpenCTI journey.</p> <p> OpenCTI Ecosystem List of available connectors and integrations to expand platform usage.</p> <p> Training Courses Training courses for analysts and administrators in the Filigran training center.</p> <p> Video materials Set of video illustrating the implementation of use cases and platform capabilities.</p> <p></p>"},{"location":"administration/csv-mappers/","title":"CSV Mappers","text":"<p>In OpenCTI, CSV Mappers allow to parse CSV files in a STIX 2.1 Object. The mappers are created and configured by users with the Manage CSV mapper capability. Then, they are available to users who import CSV files, for instance inside a report or in the global import view.</p>"},{"location":"administration/csv-mappers/#principles","title":"Principles","text":"<p>The mapper contains representations of STIX 2.1 entities and relationships, in order for the parser to properly extract them. One mapper is dedicated to parsing a specific CSV file structure, and thus dedicated mappers should be created for every specific CSV structure you might need to ingest in the platform.</p>"},{"location":"administration/csv-mappers/#create-a-new-csv-mapper","title":"Create a new CSV Mapper","text":"<p>In menu Data, select the submenu Processing, and on the right menu select CSV Mappers. You are presented with a list of all the mappers set in the platform. Note that you can delete or update any mapper from the context menu via the burger button beside each mapper.</p> <p>Click on the button + in the bottom-right corner to add a new Mapper.</p> <p>Enter a name for your mapper and some basic information about your CSV files: </p> <ul> <li>The line separator used (defaults to the standard comma character)</li> <li>The presence of a header on the first line</li> </ul> <p>Header management</p> <p>The parser will not extract any information from the CSV header if any, it will just skip the first line during parsing.</p> <p></p> <p>Then, you need to create every representation, one per entity and relationship type represented in the CSV file. Click on the + button to add an empty representation in the list, and click on the chevron to expand the section and configure the representation.</p> <p>Depending on the entity type, the form contains the fields that are either required (input outlined in red) or optional. For each field, set the corresponding columns mapping (the letter-based index of the column in the CSV table, as presented in common spreadsheet tools). </p> <p>References to other entities should be picked from the list of all the other representations already defined earlier in the mapper.</p> <p>You can do the same for all the relationships between entities that might be defined in this particular CSV file structure.</p> <p></p> <p>Fields might have options besides the mandatory column index, to help extract relevant data:</p> <ul> <li>Date values are expected in ISO 8601 format, but you can set your own format to the time parser</li> <li>Multiple values can be extracted by specifying the separator used inside the cell (e.g. <code>+</code> or <code>|</code>)</li> </ul> <p>Or to set default values in case some data is missing in the imported file.</p> <p></p>"},{"location":"administration/csv-mappers/#csv-mapper-validity","title":"CSV Mapper validity","text":"<p>The only parameter required to save a CSV Mapper is a name. The creation and refinement of its representations can be done iteratively.</p> <p>Nonetheless, all CSV Mappers go through a quick validation that checks if all the representations have all their mandatory fields set.  Only valid mappers can be run by the users on their CSV files.</p> <p>Mapper validity is visible in the list of CSV Mappers as shown below.</p> <p></p>"},{"location":"administration/csv-mappers/#test-your-csv-mapper","title":"Test your CSV mapper","text":"<p>In the creation or edition form, hit the button Test to open a dialog. Select a sample CSV file and hit the Test button.</p> <p>The code block contains the raw result of the parsing attempt, in the form of a STIX 2.1 bundle in JSON format.</p> <p>You can then check if the extracted values match the expected entities and relationships.</p> <p></p> <p>Partial test</p> <p>The test conducted in this window relies only on the translation of CSV data according to the chosen representation in the mapper. It does not take into account checks for accurate entity formatting (e.g. IPv4) or specific entity configurations (e.g. mandatory \"description\" field on reports). Consequently, the entities visible in the test window may not be created during the actual import process.</p> <p>Test with a small file</p> <p>We strongly recommend limiting test files to 100 lines and 1MB. Otherwise, the browser may crash.</p>"},{"location":"administration/csv-mappers/#use-a-mapper-for-importing-a-csv-file","title":"Use a mapper for importing a CSV file","text":"<p>You can change the default configuration of the import csv connector in your configuration file.</p> <pre><code>\"import_csv_built_in_connector\": {\n  \"enabled\": true, \n  \"interval\": 10000, \n  \"validate_before_import\": false\n},\n</code></pre> <p>In Data import section, or Data tab of an entity, when you upload a CSV, you can select a mapper to apply to the file.  The file will then be parsed following the representation rules set in the mapper.</p> <p>By default, the imported elements will be added in a new Analyst Workbench where you will be able to check the result of the import.</p>"},{"location":"administration/csv-mappers/#default-values-for-attributes","title":"Default values for attributes","text":"<p>In the case of the CSV file misses some data, you can complete it with default values. To achieve this, you have two possibilities:</p> <ul> <li>Set default values in the settings of the entities,</li> <li>Set default values directly in the CSV mapper.</li> </ul>"},{"location":"administration/csv-mappers/#set-default-values-in-the-settings-of-the-entities","title":"Set default values in the settings of the entities","text":"<p>Default value mechanisms</p> <p>Note that adding default values in settings have an impact at entity creation globally on the platform, not only on CSV mappers. If you want to apply those default values only at CSV mapper level, please use the second option.</p> <p>In settings &gt; Customization, you can select an entity type and then set default values for its attributes.</p> <p></p> <p>In the configuration of the entity, you have access to the entity's attributes that can be managed.</p> <p>Click on the attribute to add a default value information.</p> <p></p> <p>Enter the default value in the input and save the update.</p> <p></p> <p>The value filled will be used in the case where the CSV file lacks data for this attribute.</p>"},{"location":"administration/csv-mappers/#set-specific-default-values-directly-in-the-csv-mapper","title":"Set specific default values directly in the CSV mapper","text":"<p>Information retained in case of default value</p> <p>If you fill a default value in entity settings and the CSV mapper, the one from CSV mapper will be used.</p> <p>In the mapper form, you will see next to the column index input a gear icon to add extra information for the attribute. If the attribute can have a customizable default value, then you will be able to set one here.</p> <p></p> <p>The example above shows the case of the attribute <code>architecture implementation</code> of a malware. You have some information here. First, it seems we have a default value already set in entity settings for this attribute with the value <code>[powerpc, x86]</code>. However, we want to override this value with another one for our case: <code>[alpha]</code>.</p>"},{"location":"administration/csv-mappers/#specific-case-of-marking-definitions","title":"Specific case of marking definitions","text":"<p>For marking definitions, setting a default value is different from other attributes. We are not choosing a particular marking definition to use if none is specified in the CSV file. Instead, we will choose a default policy. Two option are available:</p> <ul> <li>Use the default marking definitions of the user. In this case the default marking definitions of the connected user importing the CSV file will be used,</li> <li>Let the user choose marking definitions. Here the user importing the CSV file will choose marking definitions (among the ones they can see) when selecting the CSV mapper.</li> </ul> <p></p>"},{"location":"administration/csv-mappers/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To additional content on entity customization, refers to the Customize entities page in the Administration section of the documentation.</li> </ul>"},{"location":"administration/decay-rules/","title":"Decay rules","text":"<p>Decay rules are used to update automatically indicators score in order to represent their lifecycle.</p>"},{"location":"administration/decay-rules/#configuration","title":"Configuration","text":"<p>Decay rules can be configured in the \"Settings &gt; Customization &gt; Decay rule\" menu.</p> <p></p> <p>There are built-in decay rules that can't be modified and are applied by default to indicators depending on their main observable type. Decay rules are applied from highest to lowest order (the lowest being 0).</p> <p>You can create new decay rules with higher order to apply them along with (or instead of) the built-in rules.</p> <p></p> <p>When you create a decay rule, you can specify on which indicators' main observable types it will apply. If you don't enter any, it will apply to all indicators.</p> <p>You can also add reaction points which represent the scores at which indicators are updated. For example, if you add one reaction point at 60 and another one at 40, indicators that have an initial score of 80 will be updated with a score of 60, then 40, depending on the decay curve.</p> <p>The decay curve is based on two parameters: </p> <ul> <li>the decay factor, which represents the speed at which the score falls, and</li> <li>the lifetime, which represents the time (in days) during which the value will be lowered until it reaches 0.</li> </ul> <p>Finally, the revoke score is the score at which the indicator can be revoked automatically.</p> <p></p> <p>Once you have created a new decay rule, you will be able to view its details, along with a life curve graph showing the score evolution over time.</p> <p>You will also be able to edit your rule, change all its parameters and order, activate or deactivate it (only activated rules are applied), or delete it.</p> <p></p> <p>Indicator decay manager</p> <p>Decay rules are only applied, and indicators score updated, if indicator decay manager is enabled (enabled by default). </p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/enterprise/","title":"Enterprise edition","text":"<p>Filigran</p> <p>Filigran is providing an Enterprise Edition of the platform, whether on-premise or in the SaaS.</p>"},{"location":"administration/enterprise/#what-is-opencti-ee","title":"What is OpenCTI EE?","text":"<p>OpenCTI Enterprise Edition is based on the open core concept. This means that the source code of OCTI EE remains open source and included in the main GitHub repository of the platform but is published under a specific license. As specified in the GitHub license file:</p> <ul> <li>The OpenCTI Community Edition is licensed under the Apache License, Version 2.0 (the \u201cApache License\u201d).</li> <li>The OpenCTI Enterprise Edition is licensed under the OpenCTI Enterprise Edition License (the \u201cEnterprise Edition Licensee\u201d).</li> </ul> <p>The source files in this repository have a header indicating which license they are under. If no such header is provided, this means that the file belongs to the Community Edition under the Apache License, Version 2.0.</p> <p>We wrote a complete article to explain the enterprise edition, feel free to read it to have more information</p>"},{"location":"administration/enterprise/#ee-activation","title":"EE Activation","text":"<p>Enterprise edition is easy to activate. You need to go the platform settings and click on the Activate button.</p> <p></p> <p>Then you will need to agree to the Filigran EULA. </p> <p></p> <p>As a reminder:</p> <ul> <li>OpenCTI EE is free-to-use for development, testing and research purposes as well as for non-profit organizations.</li> <li>OpenCTI EE is included for all Filigran SaaS customers without additional fee.</li> <li>For all other usages, OpenCTI EE is reserved to organizations that have signed a Filigran Enterprise agreement.</li> </ul>"},{"location":"administration/enterprise/#available-features","title":"Available features","text":""},{"location":"administration/enterprise/#activity-monitoring","title":"Activity monitoring","text":"<p>Audit logs help you answer \"who did what, where, and when?\" within your data with the maximum level of transparency. Please read Activity monitoring page to get all information.</p>"},{"location":"administration/enterprise/#playbooks-and-automation","title":"Playbooks and automation","text":"<p>OpenCTI playbooks are flexible automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform. Please read Playbook automation page to get all information.</p>"},{"location":"administration/enterprise/#organizations-management-and-segregation","title":"Organizations management and segregation","text":"<p>Organizations segregation is a way to segregate your data considering the organization associated to the users. Useful when your platform aims to share data to multiple organizations that have access to the same OpenCTI platform. Please read Organizations RBAC to get more information.</p>"},{"location":"administration/enterprise/#full-text-indexing","title":"Full text indexing","text":"<p>Full text indexing grants improved searches across structured and unstructured data. OpenCTI classic searches are based on metadata fields (e.g. title, description, type) while advanced indexing capability  enables  searches  to  be  extended  to  the document\u2019s contents. Please read File indexing to get all information.</p>"},{"location":"administration/enterprise/#more-to-come","title":"More to come","text":"<p>More features will be available in OpenCTI in the future. Features like:</p> <ul> <li>Generative AI for correlation and content generation.</li> <li>Supervised machine learning for natural language processing.</li> </ul>"},{"location":"administration/entities/","title":"Customize entities","text":""},{"location":"administration/entities/#introduction","title":"Introduction","text":"<p>A variety of entity customization options are available to optimize data representation, workflow management, and enhance overall user experience. Whether you're fine-tuning processing statuses, configuring entities' attributes, or hiding entities, OpenCTI's customization capabilities provide the flexibility you need to create a tailored environment for your threat intelligence and cybersecurity workflows.</p> <p>The following chapter aims to provide readers with an understanding of the available customization options by entity type. Customize entities can be done in \"Settings &gt; Customization\".</p> <p></p>"},{"location":"administration/entities/#hidden-in-interface","title":"Hidden in interface","text":"<p>This configuration allows to hide a specific entity type throughout the entire platform. It provides a potent means to simplify the interface and tailor it to your domain expertise. For instance, if you have no interest in disinformation campaigns, you can conceal related entities such as Narratives and Channels from the menus.</p> <p>You can specify which entities to hide on a platform-wide basis from \"Settings &gt; Customization\" and from \"Settings &gt; Parameters\", providing you with a list of hidden entities. Furthermore, you can designate hidden entities for specific Groups and Organizations from \"Settings &gt; Security &gt; Groups/Organizations\" by editing a Group/Organization.</p> <p>An overview of hidden entity types is available in the \"Hidden entity types\" field in \"Settings &gt; Parameters.\"</p>"},{"location":"administration/entities/#automatic-references-at-file-upload","title":"Automatic references at file upload","text":"<p>This configuration enables an entity to automatically construct an external reference from the uploaded file.</p>"},{"location":"administration/entities/#enforce-references","title":"Enforce references","text":"<p>This configuration enables the requirement of a reference message on an entity creation or modification. This option is helpful if you want to keep a strong consistency and traceability of your knowledge and is well suited for manual creation and update.</p> <p></p> <p></p>"},{"location":"administration/entities/#workflow","title":"Workflow","text":"<p>For now, OpenCTI has a simple workflow approach. They're represented by the \"Processing status\" field embedded in each object. By default, this field is disabled for most objects but can be activated through the platform settings:</p> <ol> <li>Navigate to \"Settings &gt; Customization &gt; Entity types &gt; [Desired object type].\"</li> <li>Click on the small pink pen icon next to \"Workflow\" to access the object customization window.</li> <li>Add and configure the desired statuses, defining their order within the workflow.</li> </ol> <p></p> <p>In addition, the available statuses are defined by a collection of status templates visible in \"Settings &gt; Taxonomies &gt; Status templates\". This collection can be customized.</p> <p></p>"},{"location":"administration/entities/#attributes","title":"Attributes","text":"<p>Each attribute in an Entity offers several customization options:</p> <ul> <li>It can be set as mandatory if not already defined as such in the STIX standard.</li> <li>A default value can be established to streamline entity creation through the creation forms.</li> <li>Different thresholds and their corresponding labels for scalable attributes can be defined.</li> </ul> <p></p>"},{"location":"administration/entities/#confidence-scale-configuration","title":"Confidence scale configuration","text":"<p>Confidence scale can be customized for each entity type by selecting another scale template or by editing directly the scale values. Once you have customized your scale, click on \"Update\" to save your configuration.</p> <p></p> <p>Max confidence level</p> <p>The above scale also needs to take into account the confidence level per user. To understand the concept, please navigate to this page</p>"},{"location":"administration/file-indexing/","title":"File indexing","text":"<p>Enterprise edition</p> <p>Platform segregation by organization is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all the information.</p>"},{"location":"administration/file-indexing/#files-search-requirements","title":"Files search requirements","text":"<p>In order to search in files, we need to extract and index files text content, which requires to have one of these database configurations :</p> <ul> <li>Elasticsearch &gt;= 8.4</li> <li>Elasticsearch &lt; 8.4 with ingest-attachment plugin</li> <li>OpenSearch with ingest-attachment plugin</li> </ul>"},{"location":"administration/file-indexing/#file-indexing-configuration","title":"File indexing configuration","text":"<p>File indexing can be configured via the <code>File indexing</code> tab in the <code>Settings</code> menu.</p> <p>The configuration and impact panel shows all file types that can be indexed, as well as the volume of storage used.</p> <p>It is also possible to include or exclude files uploaded from the global Data import panel and that are not associated with a specific entity in the platform.</p> <p>Finally, it is possible to set a maximum file size for indexing (5 Mb by default).</p> <p>Currently supported content types : <code>application/pdf</code>, <code>text/plain</code>, <code>text/csv</code>, <code>text/html</code>, <code>application/vnd.ms-excel</code>, <code>application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</code> (excel sheets).</p> <p></p> <p>Once indexing has been launched by pressing the <code>Start</code> button, you can follow its progress. </p> <p>You will also be able to <code>Pause</code> it and restart from the beginning by pressing <code>Reset</code> button which deletes all indexed files from the database.</p> <p>If you change the configuration while file indexing is running, you might need to reset in order to include newly impacted files.</p> <p>File indexing runs every 5 minutes to index last uploaded files.</p> <p></p>"},{"location":"administration/introduction/","title":"Introduction","text":"<p>This guide aims to give you a full overview of the OpenCTI features and workflows. The platform can be used in various contexts to handle threats management use cases from a technical to a more strategic level.</p>"},{"location":"administration/introduction/#administrative-settings","title":"Administrative Settings","text":"<p>The OpenCTI Administrative settings console allows administrators to configure many options dynamically within the system. As an Administrator, you can access this settings console, by clicking the settings link. </p> <p>The Settings Console allows for configuration of various aspects of the system.</p>"},{"location":"administration/introduction/#general-configuration","title":"General Configuration","text":"<ul> <li>Platform Title (Default: OpenCTI - Cyber Threat Intelligence Platform)</li> <li>Platform Favicon</li> <li>Platform General Sender email (Default: admin@opencti.io) </li> <li>Platform Default Theme (Default: Dark)</li> <li>Language (Default: Automatic Detection)</li> <li>Hidden Entity Types (Default: None)</li> </ul>"},{"location":"administration/introduction/#authentication-strategies-display","title":"Authentication Strategies Display","text":"<ul> <li>This section will show configured and enabled/disabled strategies. The configuration is done in the config/default.json file or via ENV variables detected at launch.</li> </ul>"},{"location":"administration/introduction/#platform-messages","title":"Platform Messages","text":"<ul> <li>Platform Login Message (optional) - if configured this will be displayed on the login page. This is usually used to have a welcome type message for users before login.</li> <li>Platform Consent Message (optional) - if configured this will be displayed on the login page. This is usually used to display some type of consent message for users to agree to before login. If enabled, a user must check the checkbox displayed to allow login.</li> <li>Platform Consent Confirm Text (optional) - This is displayed next to the platform consent checkbox, if Platform Consent Message is configured. Users must agree to the checkbox before the login prompt will be displayed. This message can be configured, but by default reads: I have read and comply with the above statement</li> </ul>"},{"location":"administration/introduction/#dark-theme-color-scheme","title":"Dark Theme Color Scheme","text":"<p>Various aspects of the Dark Theme can be dynamically configured in this section.</p>"},{"location":"administration/introduction/#light-theme-color-scheme","title":"Light Theme Color Scheme","text":"<p>Various aspects of the Light Theme can be dynamically configured in this section.</p>"},{"location":"administration/introduction/#tools-configuration-display","title":"Tools Configuration Display","text":"<p>This section will give general status on the various tools and enabled components of the currently configured OpenCTI deployment.</p>"},{"location":"administration/merging/","title":"Merging","text":""},{"location":"administration/merging/#data-merging","title":"Data merging","text":"<p>Within the OpenCTI platform, the merge capability is present into the \"Data &gt; Entities\" tab, and is fairly straightforward to use. To execute a merge, select the set of entities to be merged, then click on the Merge icon.</p> <p>Merging limitation</p> <p>It is not possible to merge entities of different types, nor is it possible to merge more than 4 entities at a time (it will have to be done in several stages).</p> <p></p> <p>Central to the merging process is the selection of a main entity. This primary entity becomes the anchor, retaining crucial attributes such as name and description. Other entities, while losing specific fields like descriptions, are aliased under the primary entity. This strategic decision preserves vital data while eliminating redundancy.</p> <p></p> <p>Once the choice has been made, simply validate to run the task in the background. Depending on the number of entity relationships, and the current workload on the platform, the merge may take more or less time. In the case of a healthy platform and around a hundred relationships per entity, merge is almost instantaneous.</p>"},{"location":"administration/merging/#data-preservation-and-relationship-continuity","title":"Data preservation and relationship continuity","text":"<p>A common concern when merging entities lies in the potential loss of information. In the context of OpenCTI, this worry is alleviated. Even if the merged entities were initially created by distinct sources, the platform ensures that data is not lost. Upon merging, the platform automatically generates relationships directly on the merged entity. This strategic approach ensures that all connections, regardless of their origin, are anchored to the consolidated entity. Post-merge, OpenCTI treats these once-separate entities as a singular, unified entity. Subsequent information from varied sources is channeled directly into the entity resulting from the merger. This unified entity becomes the focal point for all future relationships, ensuring the continuity of data and relationships without any loss or fragmentation.</p>"},{"location":"administration/merging/#important-considerations","title":"Important considerations","text":"<ul> <li>Irreversible process: It's essential to know that a merge operation is irreversible. Once completed, the merged entities cannot be reverted to their original state. Consequently, careful consideration and validation are crucial before initiating the merge process.</li> <li>Loss of fields in aliased entities: Fields, such as descriptions, in aliased entities - entities that have not been chosen as the main - will be lost during the merge. Ensuring that essential information is captured in the primary entity is crucial to prevent data loss.</li> </ul>"},{"location":"administration/merging/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To understand the benefits of entity merger, refer to the Merge objects page in the User Guide section of the documentation.</li> <li>Deduplication mechanism: the platform is equipped with deduplication processes that automatically merge data at creation (either manually or by importing data from different sources) if it meets certain conditions.</li> </ul>"},{"location":"administration/notifier-samples/","title":"Notifier samples","text":""},{"location":"administration/notifier-samples/#configure-teams-webhook","title":"Configure Teams webhook","text":"<p>To configure a notifier for Teams, allowing to send notifications via Teams messages, we followed the guidelines outlined in the Microsoft documentation.</p> <p></p>"},{"location":"administration/notifier-samples/#template-message-for-live-trigger","title":"Template message for live trigger","text":"<p>The Teams template message sent through webhook for a live notification is:</p> <pre><code>{\n        \"type\": \"message\",\n        \"attachments\": [\n            {\n                \"contentType\": \"application/vnd.microsoft.card.thumbnail\",\n                \"content\": {\n                    \"subtitle\": \"Operation : &lt;%=content[0].events[0].operation%&gt;\",\n                    \"text\": \"&lt;%=(new Date(notification.created)).toLocaleString()%&gt;\",\n                    \"title\": \"&lt;%=content[0].events[0].message%&gt;\",\n                    \"buttons\": [\n                        {\n                            \"type\": \"openUrl\",\n                            \"title\": \"See in OpenCTI\",\n                            \"value\": \"https://YOUR_OPENCTI_URL/dashboard/id/&lt;%=content[0].events[0].instance_id%&gt;\"\n                        }\n                    ]\n                }\n            }\n        ]\n    }\n</code></pre>"},{"location":"administration/notifier-samples/#template-message-for-digest","title":"Template message for digest","text":"<p>The Teams template message sent through webhook for a digest notification is:</p> <pre><code>{\n    \"type\": \"message\",\n    \"attachments\": [\n        {\n            \"contentType\": \"application/vnd.microsoft.card.adaptive\",\n            \"content\": {\n                \"$schema\": \"http://adaptivecards.io/schemas/adaptive-card.json\",\n                \"type\": \"AdaptiveCard\",\n                \"version\": \"1.0\",\n                \"body\": [\n                    {\n                        \"type\": \"Container\",\n                        \"items\": [\n                            {\n                                \"type\": \"TextBlock\",\n                                \"text\": \"&lt;%=notification.name%&gt;\",\n                                \"weight\": \"bolder\",\n                                \"size\": \"extraLarge\"\n                            }, {\n                                \"type\": \"TextBlock\",\n                                \"text\": \"&lt;%=(new Date(notification.created)).toLocaleString()%&gt;\",\n                                \"size\": \"medium\"\n                            }\n                        ]\n                    },\n                    &lt;% for(var i=0; i&lt;content.length; i++) { %&gt;\n                    {\n                        \"type\": \"Container\",\n                        \"items\": [&lt;% for(var j=0; j&lt;content[i].events.length; j++) { %&gt;\n                            {\n                                \"type\" : \"TextBlock\",\n                                \"text\" : \"[&lt;%=content[i].events[j].message%&gt;](https://YOUR_OPENCTI_URL/dashboard/id/&lt;%=content[i].events[j].instance_id%&gt;)\"\n                            }&lt;% if(j&lt;(content[i].events.length - 1)) {%&gt;,&lt;% } %&gt;\n                        &lt;% } %&gt;]\n           }&lt;% if(i&lt;(content.length - 1)) {%&gt;,&lt;% } %&gt;\n                    &lt;% } %&gt;\n                ]\n            }\n        }\n    ],\n   \"dataString\": &lt;%-JSON.stringify(notification)%&gt;\n}\n</code></pre>"},{"location":"administration/notifiers/","title":"Custom notifiers","text":"<p>Leveraging the platform's built-in connectors, users can create custom notifiers tailored to their unique needs. OpenCTI features three built-in connectors: a webhook connector, a simple mailer connector, and a platform mailer connector. These connectors operate based on registered schemas that describe their interaction methods.</p> <p></p>"},{"location":"administration/notifiers/#built-in-notifier-connectors","title":"Built-In notifier connectors","text":""},{"location":"administration/notifiers/#platform-mailer","title":"Platform mailer","text":"<p>This notifier connector enables customization of notifications raised within the platform. It's simple to configure, requiring only:</p> <ul> <li>Title: The title for the platform notification.</li> <li>Template: Specifies the message template for the notification.</li> </ul>"},{"location":"administration/notifiers/#simple-mailer","title":"Simple mailer","text":"<p>This notifier connector offers a straightforward approach to email notifications with simplified configuration options. Users can set:</p> <ul> <li>Title: The title for the email notification.</li> <li>Header: Additional content to include at the beginning of the email.</li> <li>Footer: Additional content to include at the end of the email.</li> <li>Logo: The option to add a logo to the email.</li> <li>Background Color: Customize the background color of the email.</li> </ul> <p></p>"},{"location":"administration/notifiers/#webhook","title":"Webhook","text":"<p>This notifier connector enables users to send notifications to external applications or services through HTTP requests. Users can specify:</p> <ul> <li>Verb: Specifies the HTTP method (GET, POST, PUT, DELETE).</li> <li>URL: Defines the destination URL for the webhook.</li> <li>Template: Specifies the message template for the notification.</li> <li>Parameters and Headers: Customizable parameters and headers sent through the webhook request.</li> </ul> <p>OpenCTI provides two notifier samples by default, designed to communicate with Microsoft Teams through a webhook. A documentation page providing details on these samples is available.</p>"},{"location":"administration/notifiers/#configuration-and-access","title":"Configuration and access","text":"<p>Custom notifiers are manageable in the \"Settings &gt; Customization &gt; Notifiers\" window and can be restricted through Role-Based Access Control (RBAC). Administrators can control access, limiting usage to specific Users, Groups, or Organizations.</p> <p>For guidance on configuring notification triggers and exploring the usages of notifiers, refer to the dedicated documentation page.</p>"},{"location":"administration/ontologies/","title":"Taxonomies","text":"<p>Taxonomies in OpenCTI refer to the structured classification systems that help in organizing and categorizing cyber threat intelligence data. They play a crucial role in the platform by allowing analysts to systematically tag and retrieve information based on predefined categories and terms.</p> <p>Along with the Customization page, these pages allow the administrator to customize the platform.</p>"},{"location":"administration/ontologies/#labels","title":"Labels","text":"<p>Labels in OpenCTI serve as a powerful tool for organizing, categorizing, and prioritizing data. Here\u2019s how they can be used effectively:</p> <ol> <li>Tagging and Categorization: Labels can be used to tag malware, incidents, or indicators (IOCs) with specific categories, making it easier to filter and search through large datasets.</li> <li>Prioritization: By labeling threats based on their severity or impact, security analysts can prioritize their response efforts accordingly.</li> <li>Correlation and Analysis: Labels help in correlating different pieces of intelligence. For example, if multiple indicators are tagged with the same label, it might indicate a larger campaign or a common adversary.</li> <li>Automation and Integration: Labels can trigger automated workflows (also called playbooks) within OpenCTI. For instance, a label might automatically initiate further investigation or escalate an incident.</li> <li>Reporting and Metrics: Labels facilitate the generation of reports and metrics, allowing organizations to track trends through dashboards, measure response effectiveness, and make data-driven decisions.</li> <li>Sharing and Collaboration: When sharing intelligence with other organizations or platforms, labels provide a common language that helps in understanding the context and relevance of the shared data.</li> </ol> <p>Tip</p> <p>In order to achieve effective data labeling methods, it is recommended to establish a clear and consistent criteria for your labeling and document them in a policy or guideline.</p>"},{"location":"administration/ontologies/#kill-chain-phases","title":"Kill chain phases","text":"<p>Kill chain phases are used in OpenCTI to structure and analyze the data related to cyber threats and attacks. They describe the stages of an attack from the perspective of the attacker and provide a framework for identifying, analysing and responding to threats.</p> <p>OpenCTI supports the following kill chain models:</p> <ul> <li>Lockheed Martin Cyber Kill Chain</li> <li>MITRE ATT&amp;CK Framework (Entreprise, PRE, Mobile and ICS)</li> <li>DISARM framework</li> </ul> <p>You can add, edit, or delete kill chain phases in the settings page, and assign them to indicators, attack patterns, incidents, or courses of action in the platform. You can also filter the data by kill chain phase, and view the kill chain phases in a timeline or as a matrix.</p> <p></p>"},{"location":"administration/ontologies/#vocabularies","title":"Vocabularies","text":"<p>Open vocabularies are sets of terms and definitions that are agreed upon by the CTI community. They help to standardize the communication documentation of cyber threat information. This section allows you to customize a set of available fields by adding vocabulary. Almost all of the drop-down menus available in the entities can be modified from this panel.</p> <p>Open vocabularies in OpenCTI are mainly based on the STIX standard.</p> <p></p>"},{"location":"administration/ontologies/#status-templates","title":"Status templates","text":"<p>Status templates are predefined statuses that can be assigned to different entities in OpenCTI, such as reports, incidents, or cases (incident responses, requests for information and requests for takedown).</p> <p>They help to track the progress of the analysis and response activities by defining statuses that are used in the workflows.</p> <p></p>"},{"location":"administration/ontologies/#case-templates","title":"Case templates","text":"<p>Customizable case templates help to streamline the process of creating cases with predefined lists of tasks.</p> <p></p>"},{"location":"administration/organization-segregation/","title":"Organization segregation","text":"<p>Enterprise edition</p> <p>Platform segregation by organization is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all the information.</p>"},{"location":"administration/organization-segregation/#organization-administration","title":"Organization administration","text":"<p>Platform administrators can promote members of an organization as \"Organization administrator\". This elevated role grants them the necessary capabilities to create, edit and delete users from the corresponding Organization. Additionally, administrators have the flexibility to define a list of groups that can be granted to newly created members by the organization administrators. This feature simplifies the process of granting appropriate access and privileges to individuals joining the organization.</p> <p></p> <p>The platform administrator can promote/demote an organization admin through its user edition form.</p> <p></p> <p>Organization admin rights</p> <p>The \"Organization admin\" has restricted access to Settings. They can only manage the members of the organizations for which they have been promoted as \"admins\".</p>"},{"location":"administration/parameters/","title":"Parameters","text":""},{"location":"administration/parameters/#description","title":"Description","text":"<p>This part of the interface wil let you configure global platform settings, like title, favicon, etc.</p> <p>It will also give you important information about the platform.</p>"},{"location":"administration/parameters/#the-configuration-section","title":"The \"Configuration\" section","text":"<p>This section allows the administrator to edit the following settings:</p> <ul> <li>Platform title</li> <li>Platform favicon URL</li> <li>Sender email address: email address displayed as sender when sending notifications. The technical sender is defined in the SMTP configuration.</li> <li>Theme</li> <li>Language</li> <li>Hidden entity types: allows you to customize which types of entities you want to see or hide in the platform. This can help you focus on the relevant information and avoid cluttering the platform with unnecessary data.</li> </ul>"},{"location":"administration/parameters/#opencti-platform","title":"OpenCTI Platform","text":"<p>This is where the Enterprise edition can be enabled.</p> <p>This section gives important information about the platform like the used version, the edition, the architecture mode (can be Standalone or Cluster) and the number used nodes.</p> <p>Through the \"Remove Filigran logos\" toggle, the administrator has the option to hide the Filigran logo on the login page and the sidebar.</p>"},{"location":"administration/parameters/#platform-announcement","title":"Platform Announcement","text":"<p>This section gives you the possibility to set and display Announcements in the platform. Those announcements will be visible to every user in the platform, on top of the interface.</p> <p>They can be used to inform some of your users or all of important information, like a scheduled downtime, an incoming upgrade, or even to share important tips regarding the usage of the platform.</p> <p>An Announcement can be accompanied by a \"Dismiss\u201d button. When clicked by a user, it makes the message disappear for this user.</p> <p></p> <p>This option can be deactivated to have a permanent announcement.</p> <p> \u26a0\ufe0f Only one announcement is shown at a time, with priority given to dismissible ones. If there are no dismissible announcements, the most recent non-dismissible one is shown.</p>"},{"location":"administration/parameters/#third-party-analytics","title":"Third-party Analytics","text":"<p>Enterprise edition</p> <p>Analytics is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have more information</p> <p>This is where you can configure analytics providers. At the moment only Google Analytics v4 is supported.</p>"},{"location":"administration/parameters/#theme-customization","title":"Theme customization","text":"<p>In this section, the administrator can customize the two OpenCTI themes </p>"},{"location":"administration/parameters/#tools","title":"Tools","text":"<p>This section informs the administrator of the statuses of the different managers used in the Platform. More information about the managers can be found here. It shows also the used versions of the search engine database, RabbitMQ and Redis.</p> <p>In cluster mode, the fact that a manager appears as enabled means that it is active in at least one node. </p> <p></p>"},{"location":"administration/policies/","title":"Policies","text":"<p>The Policies configuration window (in \"Settings &gt; Security &gt; Policies\") encompasses essential settings that govern the organizational sharing, authentication strategies, password policies, login messages, and banner appearance within the OpenCTI platform.</p>"},{"location":"administration/policies/#platform-main-organization","title":"Platform main organization","text":"<p>Allow to set a main organization for the entire platform. Users belonging to the main organization enjoy unrestricted access to all data stored in the platform. In contrast, users affiliated with other organizations will only have visibility into data explicitly shared with them.</p> <p></p> <p>Numerous repercussions linked to the activation of this feature</p> <p>This feature has implications for the entire platform and must be fully understood before being used. For example, it's mandatory to have organizations set up for each user, otherwise they won't be able to log in. It is also advisable to include connector's users in the platform main organization to avoid import problems.</p>"},{"location":"administration/policies/#authentication-strategies","title":"Authentication strategies","text":"<p>The authentication strategies section provides insights into the configured authentication methods. Additionally, an \"Enforce Two-Factor Authentication\" button is available, allowing administrators to mandate 2FA activation for users, enhancing overall account security.</p> <p>Please see the Authentication section for further details on available authentication strategies.</p> <p></p>"},{"location":"administration/policies/#local-password-policies","title":"Local password policies","text":"<p>This section encompasses a comprehensive set of parameters defining the local password policy. Administrators can specify requirements such as minimum/maximum number of characters, symbols, digits, and more to ensure robust password security across the platform. Here are all the parameters available:</p> Parameter Description <code>Number of chars must be greater than or equals to</code> Define the minimum length required for passwords. <code>Number of chars must be lower or equals to (0 equals no maximum)</code> Set an upper limit for password length. <code>Number of symbols must be greater or equals to</code> Specify the minimum number of symbols required in a password. <code>Number of digits must be greater or equals to</code> Set the minimum number of numeric characters in a password. <code>Number of words (split on hyphen, space) must be greater or equals to</code> Enforce a minimum count of words in a password. <code>Number of lowercase chars must be greater or equals to</code> Specify the minimum number of lowercase characters. <code>Number of uppercase chars must be greater or equals to</code> Specify the minimum number of uppercase characters. <p></p>"},{"location":"administration/policies/#login-messages","title":"Login messages","text":"<p>Allow to define messages on the login page to customize and highlight your platform's security policy. Three distinct messages can be customized:</p> <ul> <li>Platform login message: Appears above the login form to convey important information or announcements.</li> <li>Platform consent message: A consent message that obscures the login form until users check the approval box, ensuring informed user consent.</li> <li>Platform consent confirm text: A message accompanying the consent box, providing clarity on the consent confirmation process.</li> </ul> <p></p> <p></p>"},{"location":"administration/policies/#platform-banner-configuration","title":"Platform banner configuration","text":"<p>The platform banner configuration section allows administrators to display a custom banner message at the top and bottom of the screen. This feature enables customization for enhanced visual communication and branding within the OpenCTI platform. It can be used to add a disclaimer or system purpose.</p> <p>This configuration has two parameters:</p> <ul> <li>Platform banner level: Options defining the banner background color (Green, Red, or Yellow).</li> <li>Platform banner text: Field referencing the message to be displayed within the banner.</li> </ul> <p></p>"},{"location":"administration/policies/#maximum-marking-definitions-shareable","title":"Maximum marking definitions shareable","text":"<p>This configuration allows to define, for each type of marking definitions, until which level we allow to share data externally.</p> <p>For now this max marking definitions is used only for Public dashboard.</p> <p>For example in the capture below, for the type of marking <code>TLP</code>, only data  with a marking definition with a level equal or below <code>GREEN</code> will be shareable through Public Dashboard. And no data with marking definition <code>statement</code> will be shared at all.</p> <p></p>"},{"location":"administration/reasoning/","title":"Rules engine","text":""},{"location":"administration/reasoning/#inference-rules","title":"Inference rules","text":"<p>The rules engine comprises a set of predefined rules (named inference rules) that govern how new relationships are inferred based on existing data. These rules are carefully crafted to ensure logical and accurate relationship creation. Here is the list of existing inference rules:</p>"},{"location":"administration/reasoning/#raise-incident-based-on-sighting","title":"Raise incident based on sighting","text":"Conditions Creations A non-revoked Indicator is sighted in an Entity Creation of an Incident linked to the sighted Indicator and the targeted Entity"},{"location":"administration/reasoning/#sightings-of-observables-via-observed-data","title":"Sightings of observables via observed data","text":"Conditions Creations An Indicator is based on an Observable contained in an Observed Data Creation of a sighting between the Indicator and the creating Identity of the Observed Data"},{"location":"administration/reasoning/#sightings-propagation-from-indicator","title":"Sightings propagation from indicator","text":"Conditions Creations An Indicator based on an Observable is sighted in an Entity The Observable is sighted in the Entity"},{"location":"administration/reasoning/#sightings-propagation-from-observable","title":"Sightings propagation from observable","text":"Conditions Creations An Indicator is based on an Observable sighted in an Entity The Indicator is sighted in the Entity"},{"location":"administration/reasoning/#relation-propagation-via-an-observable","title":"Relation propagation via an observable","text":"Conditions Creations An observable is related to two Entities Create a related to relationship between the two Entities"},{"location":"administration/reasoning/#attribution-propagation","title":"Attribution propagation","text":"Conditions Creations An Entity A is attributed to an Entity B and this Entity B is itself attributed to an Entity C The Entity A is attributed to Entity C"},{"location":"administration/reasoning/#belonging-propagation","title":"Belonging propagation","text":"Conditions Creations An Entity A is part of an Entity B and this Entity B is itself part of an Entity C The Entity A is part of Entity C"},{"location":"administration/reasoning/#location-propagation","title":"Location propagation","text":"Conditions Creations A Location A is located at a Location B and this Location B is itself located at a Location C The Location A is located at Location C"},{"location":"administration/reasoning/#organization-propagation-via-participation","title":"Organization propagation via participation","text":"Conditions Creations A User is affiliated with an Organization B, which is part of an Organization C The User is affiliated to the Organization C"},{"location":"administration/reasoning/#identities-propagation-in-reports","title":"Identities propagation in reports","text":"Conditions Creations A Report contains an Identity B and this Identity B is part of an Identity C The Report contains Identity C, as well as the Relationship between Identity B and Identity C"},{"location":"administration/reasoning/#locations-propagation-in-reports","title":"Locations propagation in reports","text":"Conditions Creations A Report contains a Location B and this Location B is located at a Location C The Report contains Location B, as well as the Relationship between Location B and Location C"},{"location":"administration/reasoning/#observables-propagation-in-reports","title":"Observables propagation in reports","text":"Conditions Creations A Report contains an Indicator and this Indicator is based on an Observable The Report contains the Observable, as well as the Relationship between the Indicator and the Observable"},{"location":"administration/reasoning/#usage-propagation-via-attribution","title":"Usage propagation via attribution","text":"Conditions Creations An Entity A, attributed to an Entity C, uses an Entity B The Entity C uses the Entity B"},{"location":"administration/reasoning/#inference-of-targeting-via-a-sighting","title":"Inference of targeting via a sighting","text":"Conditions Creations An Indicator, sighted at an Entity C, indicates an Entity B The Entity B targets the Entity C"},{"location":"administration/reasoning/#targeting-propagation-via-attribution","title":"Targeting propagation via attribution","text":"Conditions Creations An Entity A, attributed to an Entity C, targets an Entity B The Entity C targets the Entity B"},{"location":"administration/reasoning/#targeting-propagation-via-belonging","title":"Targeting propagation via belonging","text":"Conditions Creations An Entity A targets an Identity B, part of an Identity C The Entity A targets the Identity C"},{"location":"administration/reasoning/#targeting-propagation-via-location","title":"Targeting propagation via location","text":"Conditions Creations An Entity targets a Location B and this Location B is located at a Location C The Entity targets the Location C"},{"location":"administration/reasoning/#targeting-propagation-when-located","title":"Targeting propagation when located","text":"Conditions Creations An Entity A targets an Entity B and this target is located at Location D. The Entity A targets the Location D"},{"location":"administration/reasoning/#rule-execution","title":"Rule execution","text":""},{"location":"administration/reasoning/#rule-activation","title":"Rule activation","text":"<p>When a rule is activated, a background task is initiated. This task scans all platform data, identifying existing relationships that meet the conditions defined by the rule. Subsequently, it creates new objects (entities and/or relationships), expanding the network of insights within your threat intelligence environment. Then, activated rules operate continuously. Whenever a relationship is created or modified, and this change aligns with the conditions specified in an active rule, the reasoning mechanism is triggered. This ensures real-time relationship inference.</p>"},{"location":"administration/reasoning/#rule-deactivation","title":"Rule deactivation","text":"<p>Deactivating a rule leads to the deletion of all objects and relationships created by it. This cleanup process maintains the accuracy and reliability of your threat intelligence database.</p>"},{"location":"administration/reasoning/#access-restrictions-and-data-impact","title":"Access restrictions and data impact","text":"<p>Access to the rule engine panel is restricted to administrators only. Regular users do not have visibility into this section of the platform. Administrators possess the authority to activate or deactivate rules.</p> <p>The rules engine empowers OpenCTI with the capability to automatically establish intricate relationships within your data. However, these rules can lead to a very large number of objects created. Even if the operation is reversible, an administrator should consider the impact of activating a rule.</p>"},{"location":"administration/reasoning/#additional-resources","title":"Additional resources","text":"<ul> <li>Usefulness: To understand the benefits and results of these rules, refer to the Inferences and reasoning page in the User Guide section of the documentation.</li> <li>New inference rule: Given the potential impact of a rule on your data, users are not allowed to add new rules. However, users can submit rule suggestions via a GitHub issue for evaluation. These suggestions are carefully evaluated by our team, ensuring continuous improvement and innovation.</li> </ul>"},{"location":"administration/retentions/","title":"Retention policies","text":"<p>Retention rules serve the purpose of establishing data retention times, specifying when data should be automatically deleted from the platform. Users can define filters to target specific objects. Any object meeting these criteria that haven't been updated within the designated time frame will be permanently deleted.</p> <p>Note that the data deleted by an active retention policy will not appear in the trash and thus cannot be restored.  </p>"},{"location":"administration/retentions/#configuration","title":"Configuration","text":"<p>Retention rules can be configured in the \"Settings &gt; Customization &gt; Retention policies\" window. A set of parameters must be configured:</p> <ul> <li>Maximum retention days: Set the maximum number of days an object can remain unchanged before being eligible for deletion.</li> <li>Filters: Define filters based on specific criteria to select the types of objects subject to retention rules.</li> </ul> <p>An object will be removed if it meets the specified filters and hasn't been updated for the duration set in the \"Maximum retention days\" field.</p> <p></p>"},{"location":"administration/retentions/#verification-process","title":"Verification process","text":"<p>Before activating a retention rule, users have the option to verify its impact using the \"Verify\" button. This action provides insight into the number of objects that currently match the rule's criteria and would be deleted if the rule is activated.</p> <p></p> <p>Verify before activation</p> <p>Always use the \"Verify\" feature to assess the potential impact of a retention rule before activating it. Once the rule is activated, data deletion will begin, and retrieval of the deleted data will not be possible.</p> <p>Retention rules contribute to maintaining a streamlined and efficient data lifecycle within OpenCTI, ensuring that outdated or irrelevant information is systematically removed from the platform, thereby optimizing disk space usage.</p>"},{"location":"administration/segregation/","title":"Marking restriction","text":"<p>Data segregation in the context of Cyber Threat Intelligence refers to the practice of categorizing and separating different types of data or information related to cybersecurity threats based on specific criteria.</p> <p>This separation helps organizations manage and analyze threat intelligence more effectively and securely and the goal of data segregation is to ensure that only those individuals who are authorized to view a particular set of data have access to that set of data.</p> <p>Practically, \"Need-to-know basis\" and \"classification level\" are data segregation measures.</p>"},{"location":"administration/segregation/#description","title":"Description","text":"<p>Marking definitions are essential in the context of data segregation to ensure that data is appropriately categorized and protected based on its sensitivity or classification level. Marking definitions establish a standardized framework for classifying data.</p> <p>Marking Definition objects are unique among STIX objects in the STIX 2.1 standard in that they cannot be versioned. This restriction is in place to prevent the possibility of indirect alterations to the markings associated with a STIX Object.</p> <p>Multiple markings can be added to the same object. Certain categories of marking definitions or trust groups may enforce rules that specify which markings take precedence over others or how some markings can be added to complement existing ones.</p> <p>In OpenCTI, data is segregated based on knowledge marking. The diagram provided below illustrates the manner in which OpenCTI establishes connections between pieces of information to authorize data access for a user:</p> <p></p>"},{"location":"administration/segregation/#manage-markings","title":"Manage markings","text":""},{"location":"administration/segregation/#create-new-markings","title":"Create new markings","text":"<p>To create a marking, you must first possess the capability <code>Manage marking definitions</code>. For further information on user administration, please refer to the Users and Role Based Access Control page.</p> <p>Once you have access to the settings, navigate to \"Settings &gt; Security &gt; Marking Definitions\" to create a new marking.</p> <p>A marking consists of the following attributes:</p> <ul> <li>Type: Specifies the marking group to which it belongs.</li> <li>Definition: The name assigned to the marking.</li> <li>Color: The color associated with the marking.</li> <li>Order: Determines the hierarchical order among markings of the same type.</li> </ul> <p></p>"},{"location":"administration/segregation/#allowed-marking","title":"Allowed marking","text":"<p>The configuration of authorized markings for a user is determined at the Group level. To access entities and relationships associated with specific markings, the user must belong to a group that has been granted access to those markings.</p> <p>There are two ways in which markings can be accessed:</p> <ul> <li>The user is a member of a group that has been granted access to the marking.</li> <li>The user is a member of a group that has access to a marking of the same type, with an equal or higher hierarchical order.</li> </ul> <p>Access to an object with several markings</p> <p>Access to all markings attached to an object is required in order to access it (not only one).</p> <p>Automatically grant access to the new marking</p> <p>To allow a group to automatically access a newly created marking definition, you can check <code>Automatically authorize this group to new marking definition</code>.</p>"},{"location":"administration/segregation/#default-marking-definitions","title":"Default marking definitions","text":"<p>To apply a default marking when creating a new entity or relationship, you can choose which marking to add by default from the list of allowed markings. You can add only one marking per type, but you can have multiple types. This configuration is also done at the Group level.</p> <p></p> <p>Need a configuration change</p> <p>Simply adding markings as default markings is insufficient to display the markings when creating an entity or relationship. You also need to enable default markings in the customization settings of an entity or relationship. For example, to enable default markings for a new report, navigate to \"Settings &gt; Customization &gt; Report &gt; Markings\" and toggle the option to <code>Activate/Desactivate default values</code>.</p>"},{"location":"administration/segregation/#management-of-multiple-markings","title":"Management of multiple markings","text":"<p>In scenarios where multiple markings of the same type but different orders are added, the platform will retain only the marking with the highest order for each type. This consolidation can occurs in various instances:</p> <ul> <li>During entity creation, if multiple markings are selected.</li> <li>During entity updates, whether manually or via a connector, if additional markings are introduced.</li> <li>When multiple entities are merged, their respective markings will be amalgamated.</li> </ul> <p>For example:</p> <p>Create a new report and add markings <code>PAP:AMBER</code>,<code>PAP:RED</code>,<code>TLP:AMBER+STRICT</code>,<code>TLP:CLEAR</code> and a statement <code>CC-BY-SA-4.0 DISARM Foundation</code></p> <p></p> <p>The final markings kept are: <code>PAP:RED</code>, <code>TLP:AMBER+STRICT</code> and <code>CC-BY-SA-4.0 DISARM Foundation</code></p> <p></p>"},{"location":"administration/segregation/#update-an-object-manually","title":"Update an object manually","text":"<p>When update an entity or a relationship:</p> <ul> <li>add a marking with the same type and different orders, a pop-up will be displayed to confirm the choice,</li> <li>add a marking with the same type and the same order, the marking will be added,</li> <li>add a marking with different types, the marking will be added.</li> </ul> <p></p>"},{"location":"administration/segregation/#import-data-from-a-connector","title":"Import data from a connector","text":"<p>As a result of this mechanism, when importing data from a connector, the connector is unable to downgrade a marking for an entity if a marking of the same type is already present on it.</p>"},{"location":"administration/segregation/#additional-information","title":"Additional information","text":"<p>The Traffic Light Protocol is implemented by default as marking definitions in OpenCTI. It allows you to segregate information by TLP levels in your platform and restrict access to marked data if users are not authorized to see the corresponding marking.</p> <p>The Traffic Light Protocol (TLP) was designed by the Forum of Incident Response and Security Teams (FIRST) to provide a standardized method for classifying and handling sensitive information, based on four categories of sensitivity.</p> <p>For more details, the diagram provided below illustrates how are categorized the marking definitions:</p> <p></p>"},{"location":"administration/support-package/","title":"Support Package","text":"<p>Support packages are useful for troubleshooting issue that occurs on OpenCTI platform. Administrators can request to create and download a support package that contains recent platform error logs and usage statistics.</p> <p>Support package content</p> <p>Even if we do our best to prevent logging any data, the support package may contains some sensitive information that you may not want to share with everyone. Before creating a ticket with your support package takes some time to check if you can safely share the content depending of your security policy.</p> <p>Support Package can be requested from \"Settings &gt; Support\" menu.</p> <p></p>"},{"location":"administration/support-package/#package-generation","title":"Package generation","text":"<p>On a click on \"Generate support package\", a support event is propagated to every platform instances to request needed information. Every instance that will receive this message will process the request and send the files to the platform. During this processing the interface will display the expected support package name in an IN PROGRESS state waiting for completion. After finishing the process the support package will move to the READY state and the buttons download and delete will be activated.</p>"},{"location":"administration/support-package/#package-download","title":"Package download","text":"<p>After file generation, using the download button will dynamically create a (zip) containing all instances logs and telemetry.</p>"},{"location":"administration/support-package/#partial-package","title":"Partial package","text":"<p>In case of platform instability, some logs might not be retrieved and the support package will be incomplete.</p> <p>If some instances fail to send their data, you will be able to force download a partial zip only after 1 minute. In case of a support package taking more than 5 minutes, the status will be moved to \"timeout\".</p>"},{"location":"administration/users/","title":"Users and Role Based Access Control","text":""},{"location":"administration/users/#introduction","title":"Introduction","text":"<p>In OpenCTI, the RBAC system not only related to what users can do or cannot do in the platform (aka. <code>Capabilities</code>) but also to the system of data segregation. Also, platform behavior such as default home dashboards, default triggers and digests as well as default hidden menus or entities can be defined across groups and organizations.</p>"},{"location":"administration/users/#high-level-design","title":"High level design","text":""},{"location":"administration/users/#roles","title":"Roles","text":"<p>Roles are used in the platform to grant the given groups with some capabilities to define what users in those groups can do or cannot do.</p>"},{"location":"administration/users/#list-of-capabilities","title":"List of capabilities","text":"Capability Description <code>Bypass all capabilities</code> Just bypass everything including data segregation and enforcements. <code>Access knowledge</code> Access in read-only to all the knowledge in the platform. <code>Access to collaborative creation</code> Create notes and opinions (and modify its own) on entities and relations. <code>Create / Update knowledge</code> Create and update existing entities and relationships. <code>Restrict organization access</code> Share entities and relationships with other organizations. <code>Delete knowledge</code> Delete entities and relationships. <code>Upload knowledge files</code> Upload files in the <code>Data</code> and <code>Content</code> section of entities. <code>Download knowledge export</code> Download the exports generated in the entities (in the <code>Data</code> section). <code>Ask for knowledge enrichment</code> Trigger an enrichment for a given entity. <code>Access Dashboards and investigations</code> Access to existing custom dashboards and investigations. <code>Create / Update Dashboards and investigations</code> Create and update custom dashboards and investigations. <code>Delete Dashboards and investigations</code> Delete existing custom dashboards and investigations. <code>Manage Public Dashboards</code> Manage public dashboards <code>Access connectors</code> Read information in the <code>Data &gt; Connectors</code> section. <code>Manage connector state</code> Reset the connector state to restart ingestion from the beginning. <code>Access data sharing &amp; ingestion</code> Access and consume data such as TAXII collections. <code>Manage data sharing &amp; ingestion</code> Share data such as TAXII collections or custom dashboards. <code>Manage CSV mappers</code> Create, update and delete CSV mappers. <code>Access administration</code> Access and manage overall parameters of the platform in <code>Settings &gt; Parameters</code>. <code>Manage credentials</code> Access and manage roles, groups, users, organizations and security policies. <code>Manage marking definitions</code> Update and delete marking definitions. <code>Manage labels &amp; Attributes</code> Update and delete labels, custom taxonomies, workflow and case templates. <code>Connectors API usage: register, ping, export push ...</code> Connectors specific permissions for register, ping, push export files, etc. <code>Connect and consume the platform streams (/stream, /stream/live)</code> List and consume the OpenCTI live streams. <code>Bypass mandatory references if any</code> If external references enforced in a type of entity, be able to bypass the enforcement."},{"location":"administration/users/#manage-roles","title":"Manage roles","text":"<p>You can manage the roles in <code>Settings &gt; Security &gt; Roles</code>.</p> <p>To create a role, just click on the <code>+</code> button:</p> <p></p> <p>Then you will be able to define the capabilities of the role:</p> <p></p>"},{"location":"administration/users/#users","title":"Users","text":"<p>You can manage the users in <code>Settings &gt; Security &gt; Users</code>. If you are using Single-Sign-On (SSO), the users in OpenCTI are automatically created upon login.</p> <p>To create a user, just click on the <code>+</code> button:</p> <p></p>"},{"location":"administration/users/#manage-a-user","title":"Manage a user","text":"<p>When access to a user, it is possible to:</p> <ul> <li>Visualize information including the token</li> <li>Modify it, reset 2FA if necessary</li> <li>Manage its sessions</li> <li>Manage its triggers and digests</li> <li>Visualize the history and operations</li> <li>Manage its max confidence levels</li> </ul> <p></p> <p>From this view you can edit the user's information by clicking the \"Update\" button, which opens a panel with several tabs.</p> <ul> <li>Overview tab: edit all basic information such as the name or language</li> <li>Password tab: change the password for this user</li> <li>Groups tab: select the groups this user belongs to</li> <li>Organization Admin tab: see Organization administration</li> <li>Confidences tab: manage the user's maximum confidence level and overrides per entity type</li> </ul> <p></p> <p>Mandatory max confidence level</p> <p>A user without Max confidence level won't have the ability to create, delete or update any data in our platform. Please be sure that your users are always either assigned to group that have a confidence level defined or that have an override of this group confidence level.</p> <p></p>"},{"location":"administration/users/#groups","title":"Groups","text":"<p>Groups are the main way to manage permissions and data segregation as well as platform customization for the given users part of this group. You can manage the groups in <code>Settings &gt; Security &gt; Groups</code>.</p> <p>Here is the description of the group available parameters.</p> Parameter Description <code>Auto new markings</code> If a new marking definition is created, this group will automatically be granted to it. <code>Default membership</code> If a new user is created (manually or upon SSO), it will be added to this group. <code>Roles</code> Roles and capabilities granted to the users belonging to this group. <code>Default dashboard</code> Customize the home dashboard for the users belonging to this group. <code>Default markings</code> In <code>Settings &gt; Customization &gt; Entity types</code>, if a default marking definition is enabled, default markings of the group is used. <code>Allowed markings</code> Grant access to the group to the defined marking definitions, more details in data segregation. <code>Triggers and digests</code> Define defaults triggers and digests for the users belonging to this group. <code>Max confidence level</code> Define the maximum confidence level for the group: it will impact the capacity to update entities, the confidence level of a newly created entity by a user of the group. <p></p> <p>Max confidence level when a user has multiple groups</p> <p>A user with multiple groups will have the the highest confidence level of all its groups.  For instance, if a user is part of group A (max confidence level = 100) and group B (max confidence level = 50), then the user max confidence level will be 100.</p>"},{"location":"administration/users/#manage-a-group","title":"Manage a group","text":"<p>When managing a group, you can define the members and all above configurations.</p> <p></p> <p></p>"},{"location":"administration/users/#organizations","title":"Organizations","text":"<p>Users can belong to organizations, which is an additional layer of data segregation and customization. To find out more about this part, please refer to the page on organization segregation.</p>"},{"location":"administration/users/#organization-administration","title":"Organization administration","text":"<p>Platform administrators can promote members of an organization as \"Organization administrator\". This elevated role grants them the necessary capabilities to create, edit and delete users from the corresponding Organization. Additionally, administrators have the flexibility to define a list of groups that can be granted to newly created members by the organization administrators. This feature simplifies the process of granting appropriate access and privileges to individuals joining the organization.</p> <p></p> <p>The platform administrator can promote/demote an organization admin through its user edition form.</p> <p></p> <p>Organization admin rights</p> <p>The \"Organization admin\" has restricted access to Settings. They can only manage the members of the organizations for which they have been promoted as \"admins\".</p>"},{"location":"administration/audit/configuration/","title":"Configuration","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p> <p>As explained in the overview page, all administration actions are listened by default.  However, all knowledge are not listened by default due to performance impact on the platform. </p> <p>For this reason you need to explicitly activate extended listening on user / group or organization.</p> <p></p> <p>Listening will start just after the configuration. Every past events will not be taken into account.</p>"},{"location":"administration/audit/events/","title":"Events","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/audit/events/#description","title":"Description","text":"<p>OpenCTI activity capability is the way to unified whats really happen in the platform. In events section you will have access to the UI that will answer to \"who did what, where, and when?\" within your data with the maximum level of transparency. </p> <p></p>"},{"location":"administration/audit/events/#include-knowledge","title":"Include knowledge","text":"<p>By default, the events screen only show you the administration actions done by the users.</p> <p>If you want to see also the information about the knowledge, you can simply activate the filter in the bar to get the complete overview of all user actions.</p> <p>Don't hesitate to read again the overview page to have a better understanding of the difference between Audit, Basic/Extended knowledge.</p>"},{"location":"administration/audit/overview/","title":"Overview","text":""},{"location":"administration/audit/overview/#overview","title":"Overview","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all the information</p> <p>OpenCTI activity capability is the way to unify what's really happening in the platform. With this feature you will be able to answer \"who did what, where, and when?\" within your data with the maximum level of transparency. </p> <p>Enabling activity helps your security, auditing, and compliance entities monitor platform for possible vulnerabilities or external data misuse.</p>"},{"location":"administration/audit/overview/#categories","title":"Categories","text":"<p>The activity groups 3 different concepts that need to be explained.</p>"},{"location":"administration/audit/overview/#basic-knowledge","title":"Basic knowledge","text":"<p>The basic knowledge refers to all STIX data knowledge inside OpenCTI. Every create/update/delete action on that knowledge is accessible through the history. That basic activity is handled by the history manager and can also be found directly on each entity.</p>"},{"location":"administration/audit/overview/#extended-knowledge","title":"Extended knowledge","text":"<p>The extended knowledge refers to extra information data to track specific user activity. As this kind of tracking is expensive, the tracking will only be done for specific users/groups/organizations explicitly configured in the configuration window.</p>"},{"location":"administration/audit/overview/#audit-knowledge","title":"Audit knowledge","text":"<p>Audit is focusing on user administration or security actions. Audit will produce console/logs files along with user interface elements.</p> <pre><code>{\n  \"auth\": \"&lt;User information&gt;\",\n  \"category\": \"AUDIT\",\n  \"level\": \"&lt;info | error&gt;\",\n  \"message\": \"&lt;human readable explanation&gt;\",\n  \"resource\": {\n    \"type\": \"&lt;authentication | mutation&gt;\",\n    \"event_scope\": \"&lt;depends on type&gt;\",\n    \"event_access\": \"&lt;administration&gt;\",\n    \"data\": \"&lt;contextual data linked to the event type&gt;\",\n    \"version\": \"&lt;version of audit log format&gt;\"\n  },\n  \"timestamp\": \"&lt;event date&gt;\",\n  \"version\": \"&lt;platform version&gt;\"\n}\n</code></pre>"},{"location":"administration/audit/overview/#architecture","title":"Architecture","text":"<p>OpenCTI uses different mechanisms to be able to publish actions (audit) or data modification (history)</p>"},{"location":"administration/audit/overview/#audit-knowledge_1","title":"Audit knowledge","text":"<p>Administration or security actions</p> <p>With Enterprise edition activated, Administration and security actions are always written; you can't configure, exclude, or disable them</p> <p> Supported</p> <p> Not supported for now</p> <p> Not applicable</p>"},{"location":"administration/audit/overview/#ingestion","title":"Ingestion","text":"Create Delete Edit Remote OCTI Streams"},{"location":"administration/audit/overview/#data-sharing","title":"Data sharing","text":"Create Delete Edit CSV Feeds TAXII Feeds Stream Feeds"},{"location":"administration/audit/overview/#connectors","title":"Connectors","text":"Create Delete Edit Connectors  State reset Works"},{"location":"administration/audit/overview/#parameters","title":"Parameters","text":"Create Delete Edit Platform parameters"},{"location":"administration/audit/overview/#security","title":"Security","text":"Create Delete Edit Roles Groups Users Sessions Policies"},{"location":"administration/audit/overview/#customization","title":"Customization","text":"Create Delete Edit Entity types Rules engine Retention policies"},{"location":"administration/audit/overview/#taxonomies","title":"Taxonomies","text":"Create Delete Edit Status templates Case templates + tasks"},{"location":"administration/audit/overview/#accesses","title":"Accesses","text":"Listen Login (success or fail) Logout Unauthorized access"},{"location":"administration/audit/overview/#extended-knowledge_1","title":"Extended knowledge","text":"<p>Extended knowledge</p> <p>Extented knowledge activity are written only if you activate the feature for a subset of users / groups or organizations</p>"},{"location":"administration/audit/overview/#data-management","title":"Data management","text":"<p>Some history actions are already included in the \"basic knowledge\". (basic marker) </p> Read Create Delete Edit Platform knowledge basic basic basic Background tasks knowledge Knowledge files basic basic Global data import files Analyst workbenches files Triggers Workspaces Investigations User profile"},{"location":"administration/audit/overview/#user-actions","title":"User actions","text":"Supported Ask for file import Ask for data enrichment Ask for export generation Execute global search"},{"location":"administration/audit/triggers/","title":"Activity triggers","text":"<p>Enterprise edition</p> <p>Activity unified interface and logging are available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"administration/audit/triggers/#description","title":"Description","text":"<p>Having all the history in the user interface (events) is sometimes not enough to have a proactive monitoring. For this reason, you can configure some specific triggers to receive notifications on audit events. You can configure like personal triggers, lives one that will be sent directly or digest depending on your needs. </p>"},{"location":"administration/audit/triggers/#configuration","title":"Configuration","text":"<p>In this type of trigger, you will need to configure various options:</p> <ul> <li>Notification target: user interface or email,</li> <li>Recipients: the recipient of the notification,</li> <li>Filters: a set of filters to get only events that really interest you.</li> </ul>"},{"location":"administration/audit/triggers/#event-structure","title":"Event structure","text":"<p>In order to correctly configure the filters, here's a definition of the event structure</p> <ul> <li> <p>Event type: <code>authentication</code></p> <ul> <li>Event scopes: <code>login</code> and <code>logout</code> </li> </ul> </li> <li> <p>Event type: <code>read</code></p> <ul> <li>Event scopes: <code>read</code> and <code>unauthorized</code> </li> </ul> </li> <li> <p>Event type: <code>file</code></p> <ul> <li>Event scopes: <code>read</code>, <code>create</code> and <code>delete</code></li> </ul> </li> <li> <p>Event type: <code>mutation</code></p> <ul> <li>Event scopes: <code>unauthorized</code>, <code>update</code>, <code>create</code> and <code>delete</code></li> </ul> </li> <li> <p>Event type: <code>command</code></p> <ul> <li>Event scopes: <code>search</code>, <code>enrich</code>, <code>import</code> and <code>export</code></li> </ul> </li> </ul>"},{"location":"deployment/authentication/","title":"Authentication","text":""},{"location":"deployment/authentication/#introduction","title":"Introduction","text":"<p>OpenCTI supports several authentication providers. If you configure multiple strategies, they will be tested in the order you declared them.</p> <p>Activation</p> <p>You need to configure/activate only the authentication strategy that you really want to propose to your users.</p> <p>The product proposes two kinds of authentication strategies:</p> <ul> <li>Form (asking user for a user/password),</li> <li>Buttons (click with authentication on an external system).</li> </ul>"},{"location":"deployment/authentication/#supported-strategies","title":"Supported Strategies","text":"<p>Under the hood, we technically use the strategies provided by PassportJS. We integrate a subset of the strategies available with passport. If you need more, we can integrate other strategies.</p>"},{"location":"deployment/authentication/#local-users-form","title":"Local users (form)","text":"<p>This strategy uses the OpenCTI database as a user management.</p> <p>OpenCTI use this strategy as the default, but it's not the one we recommend for security reasons.</p> <pre><code>\"local\": {\n    \"strategy\": \"LocalStrategy\",\n    \"config\": {\n        \"disabled\": false\n    }\n}\n</code></pre> <p>Production deployment</p> <p>Please use the LDAP/Auth0/OpenID/SAML strategy for production deployment.</p>"},{"location":"deployment/authentication/#ldap-form","title":"LDAP (form)","text":"<p>This strategy can be used to authenticate your user with your company LDAP and is based on Passport - LDAPAuth.</p> <pre><code>\"ldap\": {\n    \"strategy\": \"LdapStrategy\",\n    \"config\": {\n        \"url\": \"ldaps://mydc.domain.com:686\",\n        \"bind_dn\": \"cn=Administrator,cn=Users,dc=mydomain,dc=com\",\n        \"bind_credentials\": \"MY_STRONG_PASSWORD\",\n        \"search_base\": \"cn=Users,dc=mydomain,dc=com\",\n        \"search_filter\": \"(cn={{username}})\",\n        \"mail_attribute\": \"mail\",\n        // \"account_attribute\": \"givenName\",\n        // \"firstname_attribute\": \"cn\",\n        // \"lastname_attribute\": \"cn\",\n        \"account_attrgroup_search_filteribute\": \"givenName\",\n        \"allow_self_signed\": true\n    }\n}\n</code></pre> <p>If you would like to use LDAP groups to automatically associate LDAP groups and OpenCTI groups/organizations:</p> <pre><code>\"ldap\": {\n    \"config\": {\n        ...\n        \"group_search_base\": \"cn=Groups,dc=mydomain,dc=com\",\n        \"group_search_filter\": \"(member={{dn}})\",\n        \"groups_management\": { // To map LDAP Groups to OpenCTI Groups\n            \"group_attribute\": \"cn\",\n            \"groups_mapping\": [\"LDAP_Group_1:OpenCTI_Group_1\", \"LDAP_Group_2:OpenCTI_Group_2\", ...]\n        },\n        \"organizations_management\": { // To map LDAP Groups to OpenCTI Organizations\n            \"organizations_path\": \"cn\",\n            \"organizations_mapping\": [\"LDAP_Group_1:OpenCTI_Organization_1\", \"LDAP_Group_2:OpenCTI_Organization_2\", ...]\n        }\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#saml-button","title":"SAML (button)","text":"<p>This strategy can be used to authenticate your user with your company SAML and is based on Passport - SAML.</p> <pre><code>\"saml\": {\n    \"identifier\": \"saml\",\n    \"strategy\": \"SamlStrategy\",\n    \"config\": {\n        \"issuer\": \"mytestsaml\",\n        // \"account_attribute\": \"nameID\",\n        // \"firstname_attribute\": \"nameID\",\n        // \"lastname_attribute\": \"nameID\",\n        \"entry_point\": \"https://auth.mydomain.com/auth/realms/mydomain/protocol/saml\",\n        \"saml_callback_url\": \"http://localhost:4000/auth/saml/callback\",\n        // \"private_key\": \"MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwg...\",\n        \"cert\": \"MIICmzCCAYMCBgF2Qt3X1zANBgkqhkiG9w0BAQsFADARMQ8w...\",\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>For the SAML strategy to work:</p> <ul> <li>The <code>cert</code> parameter is mandatory (PEM format) because it is used to validate the SAML response.</li> <li>The <code>private_key</code> (PEM format) is optional and is only required if you want to sign the SAML client request.</li> </ul> <p>Certificates</p> <p>Be careful to put the <code>cert</code> / <code>private_key</code>  key in PEM format. Indeed, a lot of systems generally export the keys in X509 / PCKS12 formats and so you will need to convert them.  Here is an example to extract PEM from PCKS12: <pre><code>openssl pkcs12 -in keystore.p12 -out newfile.pem -nodes\n</code></pre></p> <p>Here is an example of SAML configuration using environment variables:</p> <pre><code>- PROVIDERS__SAML__STRATEGY=SamlStrategy \n- \"PROVIDERS__SAML__CONFIG__LABEL=Login with SAML\"\n- PROVIDERS__SAML__CONFIG__ISSUER=mydomain\n- PROVIDERS__SAML__CONFIG__ENTRY_POINT=https://auth.mydomain.com/auth/realms/mydomain/protocol/saml\n- PROVIDERS__SAML__CONFIG__SAML_CALLBACK_URL=http://opencti.mydomain.com/auth/saml/callback\n- PROVIDERS__SAML__CONFIG__CERT=MIICmzCCAYMCBgF3Rt3X1zANBgkqhkiG9w0BAQsFADARMQ8w\n- PROVIDERS__SAML__CONFIG__LOGOUT_REMOTE=false\n</code></pre> <p>OpenCTI supports mapping SAML Roles/Groups on OpenCTI Groups. Here is an example:</p> <pre><code>\"saml\": {\n    \"config\": {\n        ...,\n        // Groups mapping\n        \"groups_management\": { // To map SAML Groups to OpenCTI Groups\n            \"group_attributes\": [\"Group\"],\n            \"groups_mapping\": [\"SAML_Group_1:OpenCTI_Group_1\", \"SAML_Group_2:OpenCTI_Group_2\", ...]\n        },\n        \"groups_management\": { // To map SAML Roles to OpenCTI Groups\n            \"group_attributes\": [\"Role\"],\n            \"groups_mapping\": [\"SAML_Role_1:OpenCTI_Group_1\", \"SAML_Role_2:OpenCTI_Group_2\", ...]\n        },\n        // Organizations mapping\n        \"organizations_management\": { // To map SAML Groups to OpenCTI Organizations\n            \"organizations_path\": [\"Group\"],\n            \"organizations_mapping\": [\"SAML_Group_1:OpenCTI_Organization_1\", \"SAML_Group_2:OpenCTI_Organization_2\", ...]\n        },\n        \"organizations_management\": { // To map SAML Roles to OpenCTI Organizations\n            \"organizations_path\": [\"Role\"],\n            \"organizations_mapping\": [\"SAML_Role_1:OpenCTI_Organization_1\", \"SAML_Role_2:OpenCTI_Organization_2\", ...]\n        }\n    }\n}\n</code></pre> <p>Here is an example of SAML Groups mapping configuration using environment variables:</p> <pre><code>- \"PROVIDERS__SAML__CONFIG__GROUPS_MANAGEMENT__GROUP_ATTRIBUTES=[\\\"Group\\\"]\"\n- \"PROVIDERS__SAML__CONFIG__GROUPS_MANAGEMENT__GROUPS_MAPPING=[\\\"SAML_Group_1:OpenCTI_Group_1\\\", \\\"SAML_Group_2:OpenCTI_Group_2\\\", ...]\"\n</code></pre>"},{"location":"deployment/authentication/#auth0-button","title":"Auth0 (button)","text":"<p>This strategy allows to use Auth0 Service to handle the authentication and is based on Passport - Auth0.</p> <pre><code>\"authzero\": {\n    \"identifier\": \"auth0\",\n    \"strategy\": \"Auth0Strategy\",\n    \"config\": {\n        \"clientID\": \"XXXXXXXXXXXXXXXXXX\",\n        \"baseURL\": \"https://opencti.mydomain.com\",\n        \"clientSecret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/auth0/callback\",\n        \"domain\": \"mycompany.eu.auth0.com\",\n        \"audience\": \"XXXXXXXXXXXXXXX\",\n        \"scope\": \"openid email profile XXXXXXXXXXXXXXX\",\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>Here is an example of Auth0 configuration using environment variables:</p> <pre><code>- PROVIDERS__AUTHZERO__STRATEGY=Auth0Strategy\n- PROVIDERS__AUTHZERO__CONFIG__CLIENT_ID=${AUTH0_CLIENT_ID}\n- PROVIDERS__AUTHZERO__CONFIG__BASEURL=${AUTH0_BASE_URL}\n- PROVIDERS__AUTHZERO__CONFIG__CLIENT_SECRET=${AUTH0_CLIENT_SECRET}\n- PROVIDERS__AUTHZERO__CONFIG__CALLBACK_URL=${AUTH0_CALLBACK_URL}\n- PROVIDERS__AUTHZERO__CONFIG__DOMAIN=${AUTH0_DOMAIN}\n- \"PROVIDERS__AUTHZERO__CONFIG__SCOPE=openid email profile\"\n- PROVIDERS__AUTHZERO__CONFIG__LOGOUT_REMOTE=false\n</code></pre>"},{"location":"deployment/authentication/#openid-connect-button","title":"OpenID Connect (button)","text":"<p>This strategy allows to use the OpenID Connect Protocol to handle the authentication and is based on Node OpenID Client which is more powerful than the passport one.</p> <pre><code>\"oic\": {\n    \"identifier\": \"oic\",\n    \"strategy\": \"OpenIDConnectStrategy\",\n    \"config\": {\n        \"label\": \"Login with OpenID\",\n        \"issuer\": \"https://auth.mydomain.com/auth/realms/mydomain\",\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"redirect_uris\": [\"https://opencti.mydomain.com/auth/oic/callback\"],\n        \"logout_remote\": false\n    }\n}\n</code></pre> <p>Here is an example of OpenID configuration using environment variables:</p> <pre><code>- PROVIDERS__OPENID__STRATEGY=OpenIDConnectStrategy \n- \"PROVIDERS__OPENID__CONFIG__LABEL=Login with OpenID\"\n- PROVIDERS__OPENID__CONFIG__ISSUER=https://auth.mydomain.com/auth/realms/xxxx\n- PROVIDERS__OPENID__CONFIG__CLIENT_ID=XXXXXXXXXXXXXXXXXX\n- PROVIDERS__OPENID__CONFIG__CLIENT_SECRET=XXXXXXXXXXXXXXXXXX\n- \"PROVIDERS__OPENID__CONFIG__REDIRECT_URIS=[\\\"https://opencti.mydomain.com/auth/oic/callback\\\"]\"\n- PROVIDERS__OPENID__CONFIG__LOGOUT_REMOTE=false\n</code></pre> <p>OpenCTI support mapping OpenID Claims on OpenCTI Groups (everything is tied to a group in the platform). Here is an example:</p> <pre><code>\"oic\": {\n    \"config\": {\n        ...,\n        // Groups mapping\n        \"groups_management\": { // To map OpenID Claims to OpenCTI Groups\n            \"groups_scope\": \"groups\",\n            \"groups_path\": [\"groups\", \"realm_access.groups\", \"resource_access.account.groups\"],\n            \"groups_mapping\": [\"OpenID_Group_1:OpenCTI_Group_1\", \"OpenID_Group_2:OpenCTI_Group_2\", ...]\n        },\n        // Organizations mapping  \n        \"organizations_management\": { // To map OpenID Claims to OpenCTI Organizations\n            \"organizations_scope\": \"groups\",\n            \"organizations_path\": [\"groups\", \"realm_access.groups\", \"resource_access.account.groups\"],\n            \"organizations_mapping\": [\"OpenID_Group_1:OpenCTI_Group_1\", \"OpenID_Group_2:OpenCTI_Group_2\", ...]\n        },\n    }\n}\n</code></pre> <p>Here is an example of OpenID Groups mapping configuration using environment variables:</p> <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_SCOPE=groups\n- \"PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_PATH=[\\\"groups\\\", \\\"realm_access.groups\\\", \\\"resource_access.account.groups\\\"]\"\n- \"PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_MAPPING=[\\\"OpenID_Group_1:OpenCTI_Group_1\\\", \\\"OpenID_Group_2:OpenCTI_Group_2\\\", ...]\"\n</code></pre> <p>By default, the claims are mapped based on the content of the JWT <code>access_token</code>. If you want to map claims which are in other JWT (such as <code>id_token</code>), you can define the following environment variables:</p> <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__TOKEN_REFERENCE=id_token\n- PROVIDERS__OPENID__CONFIG__ORGANISATIONS_MANAGEMENT__TOKEN_REFERENCE=id_token\n</code></pre> <p>Alternatively, you can request OpenCTI to use claims from the <code>userinfo</code> endpoint instead of a JWT. <pre><code>- PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__READ_USERINFO=true\n- PROVIDERS__OPENID__CONFIG__ORGANISATIONS_MANAGEMENT__READ_USERINFO=true\n</code></pre></p>"},{"location":"deployment/authentication/#facebook-button","title":"Facebook (button)","text":"<p>This strategy can authenticate your users with Facebook and is based on Passport - Facebook.</p> <pre><code>\"facebook\": {\n    \"identifier\": \"facebook\",\n    \"strategy\": \"FacebookStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/facebook/callback\",\n        \"logout_remote\": false\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#google-button","title":"Google (button)","text":"<p>This strategy can authenticate your users with Google and is based on Passport - Google.</p> <pre><code>\"google\": {\n    \"identifier\": \"google\",\n    \"strategy\": \"GoogleStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/google/callback\",\n        \"logout_remote\": false\n    }\n}\n</code></pre>"},{"location":"deployment/authentication/#github-button","title":"GitHub (button)","text":"<p>This strategy can authenticate your users with GitHub and is based on Passport - GitHub.</p> <pre><code>\"github\": {\n    \"identifier\": \"github\",\n    \"strategy\": \"GithubStrategy\",\n    \"config\": {\n        \"client_id\": \"XXXXXXXXXXXXXXXXXX\",\n        \"client_secret\": \"XXXXXXXXXXXXXXXXXX\",\n        \"callback_url\": \"https://opencti.mydomain.com/auth/github/callback\",\n        \"logout_remote\": false\n  }\n}\n</code></pre>"},{"location":"deployment/authentication/#client-certificate-button","title":"Client certificate (button)","text":"<p>This strategy can authenticate a user based on SSL client certificates. For this, you need to configure OpenCTI to start in HTTPS, for example:</p> <pre><code>\"port\": 443,\n\"https_cert\": {\n    \"key\": \"/cert/server_key.pem\",\n    \"crt\": \"/cert/server_cert.pem\",\n    \"reject_unauthorized\": true\n}\n</code></pre> <p>And then add the <code>ClientCertStrategy</code>:</p> <pre><code>\"cert\": {\n    \"strategy\":\"ClientCertStrategy\",\n    \"config\": {\n        \"label\":\"CLIENT CERT\"\n    }\n}\n</code></pre> <p>Afterwards, when accessing for the first time OpenCTI, the browser will ask for the certificate you want to use.</p>"},{"location":"deployment/authentication/#proxy-headers-automatic","title":"Proxy headers (automatic)","text":"<p>This strategy can authenticate the users directly from trusted headers.</p> <pre><code>{\n  \"header\": {\n    \"strategy\": \"HeaderStrategy\",\n    \"config\": {\n      \"disabled\": false,\n      \"header_email\": \"auth_email_address\",\n      \"header_name\": \"auth_name\",\n      \"header_firstname\": \"auth_firstname\",\n      \"header_lastname\": \"auth_lastname\",\n      \"logout_uri\": \"https://www.filigran.io\",\n      \"groups_management\": {\n        \"groups_header\": \"auth_groups\",\n        \"groups_splitter\": \",\",\n        \"groups_mapping\": [\"admin:admin\", \"root:root\"]\n      },\n      \"organizations_management\": {\n        \"organizations_header\": \"auth_institution\",\n        \"organizations_splitter\": \",\",\n        \"organizations_mapping\": [\"test:test\"]\n      }\n    }\n  }\n}\n</code></pre> <p>If this mode is activated and the headers are available, the user will be automatically logged without any action or notice. The logout uri will remove the session and redirect to the configured uri. If not specified, the redirect will be done to the request referer and so the header authentication will be done again.</p>"},{"location":"deployment/authentication/#automatically-create-group-on-sso","title":"Automatically create group on SSO","text":"<p>The variable auto_create_group can be added in the options of some strategies (LDAP, SAML and OpenID). If this variable is true, the groups of a user that logins will automatically be created if they don\u2019t exist.</p> <p>More precisely, if the user that tries to authenticate has groups that don\u2019t exist in OpenCTI but exist in the SSO configuration, there are two cases:</p> <ul> <li>if auto_create_group= true in the SSO configuration: the groups are created at the platform initialization and the user will be mapped on them.</li> <li>else: an error is raised.</li> </ul> <p>Example</p> <p>We assume that Group1 exists in the platform, and newGroup doesn\u2019t exist. The user that tries to log in has the group newGroup. If auto_create_group = true in the SSO configuration, the group named newGroup will be created at the platform initialization and the user will be mapped on it. If auto_create_group = false or is undefined, the user can\u2019t log in and an error is raised.</p> <pre><code>\"groups_management\": {\n  \"group_attribute\": \"cn\",\n  \"groups_mapping\": [\"SSO_GROUP_NAME1:group1\", \"SSO_GROUP_NAME_2:newGroup\", ...]\n},\n\"auto_create_group\": true\n</code></pre>"},{"location":"deployment/authentication/#examples","title":"Examples","text":""},{"location":"deployment/authentication/#ldap-then-fallback-to-local","title":"LDAP then fallback to local","text":"<p>In this example the users have a login form and need to enter login and password. The authentication is done on LDAP first, then locally if user failed to authenticate and finally fail if none of them succeeded. Here is an example for the <code>production.json</code> file:</p> <pre><code>\"providers\": {\n    \"ldap\": {\n        \"strategy\": \"LdapStrategy\",\n        \"config\": {\n            \"url\": \"ldaps://mydc.mydomain.com:636\",\n            \"bind_dn\": \"cn=Administrator,cn=Users,dc=mydomain,dc=com\",\n            \"bind_credentials\": \"MY_STRONG_PASSWORD\",\n            \"search_base\": \"cn=Users,dc=mydomain,dc=com\",\n            \"search_filter\": \"(cn={{username}})\",\n            \"mail_attribute\": \"mail\",\n            \"account_attribute\": \"givenName\"\n        }\n    },\n    \"local\": {\n        \"strategy\": \"LocalStrategy\",\n        \"config\": {\n            \"disabled\": false\n        }\n    }\n}\n</code></pre> <p>If you use a container deployment, here is an example using environment variables:</p> <pre><code>- PROVIDERS__LDAP__STRATEGY=LdapStrategy\n- PROVIDERS__LDAP__CONFIG__URL=ldaps://mydc.mydomain.org:636\n- PROVIDERS__LDAP__CONFIG__BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=com\n- PROVIDERS__LDAP__CONFIG__BIND_CREDENTIALS=XXXXXXXXXX\n- PROVIDERS__LDAP__CONFIG__SEARCH_BASE=cn=Users,dc=mydomain,dc=com\n- PROVIDERS__LDAP__CONFIG__SEARCH_FILTER=(cn={{username}})\n- PROVIDERS__LDAP__CONFIG__MAIL_ATTRIBUTE=mail\n- PROVIDERS__LDAP__CONFIG__ACCOUNT_ATTRIBUTE=givenName\n- PROVIDERS__LDAP__CONFIG__ALLOW_SELF_SIGNED=true\n- PROVIDERS__LOCAL__STRATEGY=LocalStrategy\n</code></pre>"},{"location":"deployment/clustering/","title":"Clustering","text":""},{"location":"deployment/clustering/#introduction","title":"Introduction","text":"<p>The OpenCTI platform technological stack has been designed to be able to scale horizontally. All dependencies such as Elastic or Redis can be deployed in cluster mode and performances can be drastically increased by deploying multiple platform and worker instances.</p>"},{"location":"deployment/clustering/#high-level-architecture","title":"High level architecture","text":"<p>Here is the high level architecture for customers and Filigran cloud platform to ensure both high availability and throughput.</p> <p></p>"},{"location":"deployment/clustering/#configuration","title":"Configuration","text":""},{"location":"deployment/clustering/#dependencies","title":"Dependencies","text":""},{"location":"deployment/clustering/#elasticsearch","title":"ElasticSearch","text":"<p>In the ElasticSearch configuration of OpenCTI, it is possible to declare all nodes.</p> <pre><code>- \"ELASTICSEARCH__URL=[\\\"https://user:pass@node1:9200\\\", \\\"https://user:pass@node2:9200\\\", ...]\"\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with OpenSearch and AWS / GCP / Azure native search services based on the ElasticSearch query language.</p>"},{"location":"deployment/clustering/#redis","title":"Redis","text":"<p>Redis should be turned to cluster mode:</p> <pre><code>- REDIS__MODE=cluster\n- \"REDIS__HOSTNAMES=[\\\"node1:6379\\\", \\\"node2:6379\\\", ...]\"\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with ElastiCache, MemoryStore and AWS / GCP / Azure native services based on the Redis protocol.</p>"},{"location":"deployment/clustering/#rabbitmq","title":"RabbitMQ","text":"<p>For the RabbitMQ cluster, you will need a TCP load balancer on top of the nodes since the configuration does not support multi-nodes for now:</p> <pre><code>- RABBITMQ__HOSTNAME=load-balancer-rabbitmq\n</code></pre> <p>Compatibility</p> <p>OpenCTI is also compatible with Amazon MQ, CloudAMQP and AWS / GCP / Azure native services based on the AMQP protocol.</p>"},{"location":"deployment/clustering/#s3-bucket-minio","title":"S3 bucket / MinIO","text":"<p>MinIO is an open source server able to serve S3 buckets. It can be deployed in cluster mode and is compatible with several storage backend. OpenCTI is compatible with any tool following the S3 standard.</p>"},{"location":"deployment/clustering/#platform","title":"Platform","text":"<p>As showed on the schema, best practices for cluster mode and to avoid any congestion in the technological stack are:</p> <ul> <li>Deploy platform(s) dedicated to end users and connectors registration</li> <li>Deploy platform(s) dedicated to workers / ingestion process<ul> <li>We recommend 3 to 4 workers maximum by OpenCTI instance.</li> <li>The ingestion platforms will never be accessed directly by end users.</li> </ul> </li> </ul> <p>When enabling clustering, the number of nodes is displayed in Settings &gt; Parameters.</p> <p></p>"},{"location":"deployment/clustering/#managers-and-schedulers","title":"Managers and schedulers","text":"<p>Also, since some managers like the rule engine, the task manager and the notification manager can take some resources in the OpenCTI NodeJS process, it is highly recommended to disable them in the frontend cluster. OpenCTI automatically handle the distribution and the launching of the engines across all nodes in the cluster except where they are explicitly disabled in the configuration.</p> <p></p>"},{"location":"deployment/configuration/","title":"Configuration","text":"<p>The purpose of this section is to learn how to configure OpenCTI to have it tailored for your production and development needs. It is possible to check all default parameters implemented in the platform in the <code>default.json</code> file.</p> <p>Here are the configuration keys, for both containers (environment variables) and manual deployment.</p> <p>Parameters equivalence</p> <p>The equivalent of a config variable in environment variables is the usage of a double underscores (<code>__</code>) for a level of config.</p> <p>For example: <pre><code>\"providers\": {\n  \"ldap\": {\n    \"strategy\": \"LdapStrategy\"\n  }\n}\n</code></pre></p> <p>will become: <pre><code>PROVIDERS__LDAP__STRATEGY=LdapStrategy\n</code></pre></p> <p>If you need to put a list of elements for the key, it must have a special formatting. Here is an example for redirect URIs for OpenID config: <pre><code>\"PROVIDERS__OPENID__CONFIG__REDIRECT_URIS=[\\\"https://demo.opencti.io/auth/oic/callback\\\"]\"\n</code></pre></p>"},{"location":"deployment/configuration/#platform","title":"Platform","text":""},{"location":"deployment/configuration/#api-frontend","title":"API &amp; Frontend","text":""},{"location":"deployment/configuration/#basic-parameters","title":"Basic parameters","text":"Parameter Environment variable Default value Description app:port APP__PORT 4000 Listen port of the application app:base_path APP__BASE_PATH Specific URI (ie. /opencti) app:base_url APP__BASE_URL http://localhost:4000 Full URL of the platform (should include the <code>base_path</code> if any) app:request_timeout APP__REQUEST_TIMEOUT 1200000 Request timeout, in ms (default 20 minutes) app:session_timeout APP__SESSION_TIMEOUT 1200000 Session timeout, in ms (default 20 minutes) app:session_idle_timeout APP__SESSION_IDLE_TIMEOUT 0 Idle timeout (locking the screen), in ms (default 0 minute - disabled) app:session_cookie APP__SESSION_COOKIE false Use memory/session cookie instead of persistent one app:admin:email APP__ADMIN__EMAIL admin@opencti.io Default login email of the admin user app:admin:password APP__ADMIN__PASSWORD ChangeMe Default password of the admin user app:admin:token APP__ADMIN__TOKEN ChangeMe Default token (must be a valid UUIDv4) app:health_access_key APP__HEALTH_ACCESS_KEY ChangeMe Access key for the <code>/health</code> endpoint. Must be changed - will not respond to default value. Access with <code>/health?health_access_key=ChangeMe</code>"},{"location":"deployment/configuration/#network-and-security","title":"Network and security","text":"Parameter Environment variable Default value Description http_proxy HTTP_PROXY Proxy URL for HTTP connection (example: http://proxy:80080) https_proxy HTTPS_PROXY Proxy URL for HTTPS connection (example: http://proxy:80080) no_proxy NO_PROXY Comma separated list of hostnames for proxy exception (example: localhost,127.0.0.0/8,internal.opencti.io) app:https_cert:cookie_secure APP__HTTPS_CERT__COOKIE_SECURE false Set the flag \"secure\" for session cookies. app:https_cert:ca APP__HTTPS_CERT__CA Empty list [] Certificate authority paths or content, only if the client uses a self-signed certificate. app:https_cert:key APP__HTTPS_CERT__KEY Certificate key path or content app:https_cert:crt APP__HTTPS_CERT__CRT Certificate crt path or content app:https_cert:reject_unauthorized APP__HTTPS_CERT__REJECT_UNAUTHORIZED If not false, the server certificate is verified against the list of supplied CAs"},{"location":"deployment/configuration/#logging","title":"Logging","text":""},{"location":"deployment/configuration/#errors","title":"Errors","text":"Parameter Environment variable Default value Description app:app_logs:logs_level APP__APP_LOGS__LOGS_LEVEL info The application log level app:app_logs:logs_files APP__APP_LOGS__LOGS_FILES <code>true</code> If application logs is logged into files app:app_logs:logs_console APP__APP_LOGS__LOGS_CONSOLE <code>true</code> If application logs is logged to console (useful for containers) app:app_logs:logs_max_files APP__APP_LOGS__LOGS_MAX_FILES 7 Maximum number of daily files in logs app:app_logs:logs_directory APP__APP_LOGS__LOGS_DIRECTORY ./logs File logs directory"},{"location":"deployment/configuration/#audit","title":"Audit","text":"Parameter Environment variable Default value Description app:audit_logs:logs_files APP__AUDIT_LOGS__LOGS_FILES <code>true</code> If audit logs is logged into files app:audit_logs:logs_console APP__AUDIT_LOGS__LOGS_CONSOLE <code>true</code> If audit logs is logged to console (useful for containers) app:audit_logs:logs_max_files APP__AUDIT_LOGS__LOGS_MAX_FILES 7 Maximum number of daily files in logs app:audit_logs:logs_directory APP__AUDIT_LOGS__LOGS_DIRECTORY ./logs Audit logs directory"},{"location":"deployment/configuration/#telemetry","title":"Telemetry","text":"Parameter Environment variable Default value Description app:telemetry:metrics:enabled APP__TELEMETRY__METRICS__ENABLED <code>false</code> Enable the metrics collection. app:telemetry:metrics:exporter_otlp APP__TELEMETRY__METRICS__EXPORTER_OTLP Port to expose the OTLP endpoint. app:telemetry:metrics:exporter_prometheus APP__TELEMETRY__METRICS__EXPORTER_PROMETHEUS 14269 Port to expose the Prometheus endpoint."},{"location":"deployment/configuration/#maps-references","title":"Maps &amp; references","text":"Parameter Environment variable Default value Description app:map_tile_server_dark APP__MAP_TILE_SERVER_DARK https://map.opencti.io/styles/filigran-dark2/{z}/{x}/{y}.png The address of the OpenStreetMap provider with dark theme style app:map_tile_server_light APP__MAP_TILE_SERVER_LIGHT https://map.opencti.io/styles/filigran-light2/{z}/{x}/{y}.png The address of the OpenStreetMap provider with light theme style app:reference_attachment APP__REFERENCE_ATTACHMENT <code>false</code> External reference mandatory attachment"},{"location":"deployment/configuration/#functional-customization","title":"Functional customization","text":"Parameter Environment variable Default value Description app:artifact_zip_password APP__ARTIFACT_ZIP_PASSWORD infected Artifact encrypted archive default password relations_deduplication:past_days RELATIONS_DEDUPLICATION__PAST_DAYS 30 De-duplicate relations based on <code>start_time</code> and <code>stop_time</code> - n days relations_deduplication:next_days RELATIONS_DEDUPLICATION__NEXT_DAYS 30 De-duplicate relations based on <code>start_time</code> and <code>stop_time</code> + n days relations_deduplication:created_by_based RELATIONS_DEDUPLICATION__CREATED_BY_BASED <code>false</code> Take into account the author to duplicate even if <code>stat_time</code> / <code>stop_time</code> are matching relations_deduplication:types_overrides:relationship_type:past_days RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__PAST_DAYS Override the past days for a specific type of relationship (ex. targets) relations_deduplication:types_overrides:relationship_type:next_days RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__NEXT_DAYS Override the next days for a specific type of relationship (ex. targets) relations_deduplication:types_overrides:relationship_type:created_by_based RELATIONS_DEDUPLICATION__RELATIONSHIP_TYPE__CREATED_BY_BASED Override the author duplication for a specific type of relationship (ex. targets)"},{"location":"deployment/configuration/#technical-customization","title":"Technical customization","text":"Parameter Environment variable Default value Description app:graphql:playground:enabled APP__GRAPHQL__PLAYGROUND__ENABLED <code>true</code> Enable the playground on /graphql app:graphql:playground:force_disabled_introspection APP__GRAPHQL__PLAYGROUND__FORCE_DISABLED_INTROSPECTION <code>true</code> Introspection is allowed to auth users but can be disabled in needed app:concurrency:retry_count APP__CONCURRENCY__RETRY_COUNT 200 Number of try to get the lock to work an element (create/update/merge, ...) app:concurrency:retry_delay APP__CONCURRENCY__RETRY_DELAY 100 Delay between 2 lock retry (in milliseconds) app:concurrency:retry_jitter APP__CONCURRENCY__RETRY_JITTER 50 Random jitter to prevent concurrent retry  (in milliseconds) app:concurrency:max_ttl APP__CONCURRENCY__MAX_TTL 30000 Global maximum time for lock retry (in milliseconds)"},{"location":"deployment/configuration/#dependencies","title":"Dependencies","text":""},{"location":"deployment/configuration/#xtm-suite","title":"XTM Suite","text":"Parameter Environment variable Default value Description xtm:openbas_url XTM__OPENBAS_URL OpenBAS URL xtm:openbas_token XTM__OPENBAS_TOKEN OpenBAS token xtm:openbas_reject_unauthorized XTM__OPENBAS_REJECT_UNAUTHORIZED false Enable TLS certificate check xtm:openbas_disable_display XTM__OPENBAS_DISABLE_DISPLAY false Disable OpenBAS posture in the UI"},{"location":"deployment/configuration/#elasticsearch","title":"ElasticSearch","text":"Parameter Environment variable Default value Description elasticsearch:engine_selector ELASTICSEARCH__ENGINE_SELECTOR auto <code>elk</code> or <code>opensearch</code>, default is <code>auto</code>, please put <code>elk</code> if you use token auth. elasticsearch:engine_check ELASTICSEARCH__ENGINE_CHECK false Disable Search Engine compatibility matrix verification.  Caution: OpenCTI was developed in compliance with the compatibility matrix. Setting the parameter to <code>true</code> may result in negative impacts. elasticsearch:url ELASTICSEARCH__URL http://localhost:9200 URL(s) of the ElasticSearch (supports http://user:pass@localhost:9200 and list of URLs) elasticsearch:username ELASTICSEARCH__USERNAME Username can be put in the URL or with this parameter elasticsearch:password ELASTICSEARCH__PASSWORD Password can be put in the URL or with this parameter elasticsearch:api_key ELASTICSEARCH__API_KEY API key for ElasticSearch token auth. Please set also <code>engine_selector</code> to <code>elk</code> elasticsearch:index_prefix ELASTICSEARCH__INDEX_PREFIX opencti Prefix for the indices elasticsearch:ssl:reject_unauthorized ELASTICSEARCH__SSL__REJECT_UNAUTHORIZED <code>true</code> Enable TLS certificate check elasticsearch:ssl:ca ELASTICSEARCH__SSL__CA Custom certificate path or content elasticsearch:search_wildcard_prefix ELASTICSEARCH__SEARCH_WILDCARD_PREFIX <code>false</code> Search includes words with automatic fuzzy comparison elasticsearch:search_fuzzy ELASTICSEARCH__SEARCH_FUZZY <code>false</code> Search will include words not starting with the search keyword"},{"location":"deployment/configuration/#redis","title":"Redis","text":"Parameter Environment variable Default value Description redis:mode REDIS__MODE single Connect to redis in \"single\", \"sentinel or \"cluster\"  mode redis:namespace REDIS__NAMESPACE Namespace (to use as prefix) redis:hostname REDIS__HOSTNAME localhost Hostname of the Redis Server redis:hostnames REDIS__HOSTNAMES Hostnames definition for Redis cluster or sentinel mode: a list of host:port objects. redis:port REDIS__PORT 6379 Port of the Redis Server redis:sentinel_master_name REDIS__SENTINEL_MASTER_NAME Name of your Redis Sentinel Master (mandatory in sentinel mode) redis:use_ssl REDIS__USE_SSL <code>false</code> Is the Redis Server has TLS enabled redis:username REDIS__USERNAME Username of the Redis Server redis:password REDIS__PASSWORD Password of the Redis Server redis:ca REDIS__CA [] List of path(s) of the CA certificate(s) redis:trimming REDIS__TRIMMING 2000000 Number of elements to maintain in the stream. (0 = unlimited)"},{"location":"deployment/configuration/#rabbitmq","title":"RabbitMQ","text":"Parameter Environment variable Default value Description rabbitmq:hostname RABBITMQ__HOSTNAME localhost 7 Hostname of the RabbitMQ server rabbitmq:port RABBITMQ__PORT 5672 Port of the RabbitMQ server rabbitmq:port_management RABBITMQ__PORT_MANAGEMENT 15672 Port of the RabbitMQ Management Plugin rabbitmq:username RABBITMQ__USERNAME guest RabbitMQ user rabbitmq:password RABBITMQ__PASSWORD guest RabbitMQ password rabbitmq:queue_type RABBITMQ__QUEUE_TYPE \"classic\" RabbitMQ Queue Type (\"classic\" or \"quorum\") - - - - rabbitmq:use_ssl RABBITMQ__USE_SSL <code>false</code> Use TLS connection rabbitmq:use_ssl_cert RABBITMQ__USE_SSL_CERT Path or cert content rabbitmq:use_ssl_key RABBITMQ__USE_SSL_KEY Path or key content rabbitmq:use_ssl_pfx RABBITMQ__USE_SSL_PFX Path or pfx content rabbitmq:use_ssl_ca RABBITMQ__USE_SSL_CA [] List of path(s) of the CA certificate(s) rabbitmq:use_ssl_passphrase RABBITMQ__SSL_PASSPHRASE Passphrase for the key certificate rabbitmq:use_ssl_reject_unauthorized RABBITMQ__SSL_REJECT_UNAUTHORIZED <code>false</code> Reject rabbit self signed certificate - - - - rabbitmq:management_ssl RABBITMQ__MANAGEMENT_SSL <code>false</code> Is the Management Plugin has TLS enabled rabbitmq:management_ssl_reject_unauthorized RABBITMQ__SSL_REJECT_UNAUTHORIZED <code>true</code> Reject management self signed certificate"},{"location":"deployment/configuration/#s3-bucket","title":"S3 Bucket","text":"Parameter Environment variable Default value Description minio:endpoint MINIO__ENDPOINT localhost Hostname of the S3 Service. Example if you use AWS Bucket S3: s3.us-east-1.amazonaws.com (if <code>minio:bucket_region</code> value is us-east-1). This parameter value can be omitted if you use Minio as an S3 Bucket Service. minio:port MINIO__PORT 9000 Port of the S3 Service. For AWS Bucket S3 over HTTPS, this value can be changed (usually 443). minio:use_ssl MINIO__USE_SSL <code>false</code> Indicates whether the S3 Service has TLS enabled. For AWS Bucket S3 over HTTPS, this value could be <code>true</code>. minio:access_key MINIO__ACCESS_KEY ChangeMe Access key for the S3 Service. minio:secret_key MINIO__SECRET_KEY ChangeMe Secret key for the S3 Service. minio:bucket_name MINIO__BUCKET_NAME opencti-bucket S3 bucket name. Useful to change if you use AWS. minio:bucket_region MINIO__BUCKET_REGION us-east-1 Region of the S3 bucket if you are using AWS. This parameter value can be omitted if you use Minio as an S3 Bucket Service. minio:use_aws_role MINIO__USE_AWS_ROLE <code>false</code> Indicates whether to use AWS role auto credentials. When this parameter is configured, the <code>minio:access_key</code> and <code>minio:secret_key</code> parameters are not necessary."},{"location":"deployment/configuration/#smtp-service","title":"SMTP Service","text":"Parameter Environment variable Default value Description smtp:hostname SMTP__HOSTNAME SMTP Server hostname smtp:port SMTP__PORT 465 SMTP Port (25 or 465 for TLS) smtp:use_ssl SMTP__USE_SSL <code>false</code> SMTP over TLS smtp:reject_unauthorized SMTP__REJECT_UNAUTHORIZED <code>false</code> Enable TLS certificate check smtp:username SMTP__USERNAME SMTP Username if authentication is needed smtp:password SMTP__PASSWORD SMTP Password if authentication is needed"},{"location":"deployment/configuration/#ai-service","title":"AI Service","text":"<p>AI deployment and cloud services</p> <p>There are several possibilities for Enterprise Edition customers to use OpenCTI AI endpoints:</p> <ul> <li>Use the Filigran AI Service leveraging our custom AI model using the token given by the support team.</li> <li>Use OpenAI or MistralAI cloud endpoints using your own tokens.</li> <li>Deploy or use local AI endpoints (Filigran can provide you with the custom model).</li> </ul> Parameter Environment variable Default value Description ai:enabled AI__ENABLED true Enable AI capabilities ai:type AI__TYPE mistralai AI type (<code>mistralai</code> or <code>openai</code>) ai:endpoint AI__ENDPOINT Endpoint URL (empty means default cloud service) ai:token AI__TOKEN Token for endpoint credentials ai:model AI__MODEL Model to be used for text generation (depending on type) ai:model_images AI__MODEL_IMAGES Model to be used for image generation (depending on type)"},{"location":"deployment/configuration/#using-a-credentials-provider","title":"Using a credentials provider","text":"<p>In some cases, it may not be possible to put directly dependencies credentials directly in environment variables or static configuration. The platform can then retrieve them from a credentials provider. Here is the list of supported providers:</p> Credentials provider Provider key CyberArk <code>cyberark</code> <p>For each dependency, special configuration keys are available to ensure the platform retrieves credentials during start process. Not all dependencies support this mechanism, here is the exhaustive list:</p> Dependency Prefix ElasticSearch <code>elasticsearch</code> S3 Storage <code>minio</code> Redis <code>redis</code> OpenID secrets <code>oic</code>"},{"location":"deployment/configuration/#common-configurations","title":"Common configurations","text":"Parameter Environment variable Default value Description <code>{prefix}</code>:credentials_provider:https_cert:reject_unauthorized <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__REJECT_UNAUTHORIZED <code>false</code> Reject unauthorized TLS connection <code>{prefix}</code>:credentials_provider:https_cert:crt <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__CRT Path to the HTTPS certificate <code>{prefix}</code>:credentials_provider:https_cert:key <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__KEY Path to the HTTPS key <code>{prefix}</code>:credentials_provider:https_cert:ca <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__HTTPS_CERT__CA Path to the HTTPS CA certificate"},{"location":"deployment/configuration/#cyberark","title":"CyberArk","text":"Parameter Environment variable Default value Description <code>{prefix}</code>:credentials_provider:cyberark:uri <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__URI The URL of the CyberArk endpoint for credentials retrieval (GET request) <code>{prefix}</code>:credentials_provider:cyberark:app_id <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__APP_ID The used application ID for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:safe <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__SAFE The used safe key for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:object <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__OBJECT The used object key for the dependency within CyberArk <code>{prefix}</code>:credentials_provider:cyberark:default_splitter <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER : Default splitter of the credentials results, for \"username:password\", default is \":\" <code>{prefix}</code>:credentials_provider:cyberark:field_targets <code>{PREFIX}</code>__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS [] Fields targets in the data content response after splitting <p>Here is an example for ElasticSearch:</p> <p>Environment variables: <pre><code>- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__URI=http://my.cyberark.com/AIMWebService/api/Accounts\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__APP_ID=opencti-elastic\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__SAFE=mysafe-key\n- ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__OBJECT=myobject-key\n- \"ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER=:\" # As default is already \":\", may not be necessary\n- \"ELASTICSEARCH__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS=[\\\"username\\\",\\\"password\\\"]\"\n</code></pre></p> <p>JSON version: <pre><code>\"elasticsearch\": {\n    \"credentials_provider\": {\n        \"cyberark\": {\n            \"uri\": \"http://my.cyberark.com/AIMWebService/api/Accounts\",\n            \"app_id\": \"opencti-elastic\",\n            \"safe\": \"mysafe-key\",\n            \"object\": \"myobject-key\",\n            \"default_splitter\": \":\",\n            \"field_targets\": [\"username\", \"password\"]\n      }\n    }\n}\n</code></pre></p> <p>Another example for MinIo (S3) using certificate:</p> <p>Environment variables: <pre><code>- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__CRT=/cert_volume/mycert.crt\n- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__KEY=/cert_volume/mycert.key\n- MINIO__CREDENTIALS_PROVIDER__HTTPS_CERT__CA=/cert_volume/ca.crt\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__URI=http://my.cyberark.com/AIMWebService/api/Accounts\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__APP_ID=opencti-s3\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__SAFE=mysafe-key\n- MINIO__CREDENTIALS_PROVIDER__CYBERARK__OBJECT=myobject-key\n- \"MINIO__CREDENTIALS_PROVIDER__CYBERARK__DEFAULT_SPLITTER=:\" # As default is already \":\", may not be necessary\n- \"MINIO__CREDENTIALS_PROVIDER__CYBERARK__FIELD_TARGETS=[\\\"access_key\\\",\\\"secret_key\\\"]\"\n</code></pre></p>"},{"location":"deployment/configuration/#engines-schedules-and-managers","title":"Engines, Schedules and Managers","text":"Parameter Environment variable Default value Description rule_engine:enabled RULE_ENGINE__ENABLED <code>true</code> Enable/disable the rule engine rule_engine:lock_key RULE_ENGINE__LOCK_KEY rule_engine_lock Lock key of the engine in Redis - - - - history_manager:enabled HISTORY_MANAGER__ENABLED <code>true</code> Enable/disable the history manager history_manager:lock_key HISTORY_MANAGER__LOCK_KEY history_manager_lock Lock key for the manager in Redis - - - - task_scheduler:enabled TASK_SCHEDULER__ENABLED <code>true</code> Enable/disable the task scheduler task_scheduler:lock_key TASK_SCHEDULER__LOCK_KEY task_manager_lock Lock key for the scheduler in Redis task_scheduler:interval TASK_SCHEDULER__INTERVAL 10000 Interval to check new task to do (in ms) - - - - sync_manager:enabled SYNC_MANAGER__ENABLED <code>true</code> Enable/disable the sync manager sync_manager:lock_key SYNC_MANAGER__LOCK_KEY sync_manager_lock Lock key for the manager in Redis sync_manager:interval SYNC_MANAGER__INTERVAL 10000 Interval to check new sync feeds to consume (in ms) - - - - expiration_scheduler:enabled EXPIRATION_SCHEDULER__ENABLED <code>true</code> Enable/disable the scheduler expiration_scheduler:lock_key EXPIRATION_SCHEDULER__LOCK_KEY expired_manager_lock Lock key for the scheduler in Redis expiration_scheduler:interval EXPIRATION_SCHEDULER__INTERVAL 300000 Interval to check expired indicators (in ms) - - - - retention_manager:enabled RETENTION_MANAGER__ENABLED <code>true</code> Enable/disable the retention manager retention_manager:lock_key RETENTION_MANAGER__LOCK_KEY retention_manager_lock Lock key for the manager in Redis retention_manager:interval RETENTION_MANAGER__INTERVAL 60000 Interval to check items to be deleted (in ms) - - - - notification_manager:enabled NOTIFICATION_MANAGER__ENABLED <code>true</code> Enable/disable the notification manager notification_manager:lock_live_key NOTIFICATION_MANAGER__LOCK_LIVE_KEY notification_live_manager_lock Lock live key for the manager in Redis notification_manager:lock_digest_key NOTIFICATION_MANAGER__LOCK_DIGEST_KEY notification_digest_manager_lock Lock digest key for the manager in Redis notification_manager:interval NOTIFICATION_MANAGER__INTERVAL 10000 Interval to push notifications - - - - publisher_manager:enabled PUBLISHER_MANAGER__ENABLED <code>true</code> Enable/disable the publisher manager publisher_manager:lock_key PUBLISHER_MANAGER__LOCK_KEY publisher_manager_lock Lock key for the manager in Redis publisher_manager:interval PUBLISHER_MANAGER__INTERVAL 10000 Interval to send notifications / digests (in ms) - - - - ingestion_manager:enabled INGESTION_MANAGER__ENABLED <code>true</code> Enable/disable the ingestion manager ingestion_manager:lock_key INGESTION_MANAGER__LOCK_KEY ingestion_manager_lock Lock key for the manager in Redis ingestion_manager:interval INGESTION_MANAGER__INTERVAL 300000 Interval to check for new data in remote feeds - - - - playbook_manager:enabled PLAYBOOK_MANAGER__ENABLED <code>true</code> Enable/disable the playbook manager playbook_manager:lock_key PLAYBOOK_MANAGER__LOCK_KEY publisher_manager_lock Lock key for the manager in Redis playbook_manager:interval PLAYBOOK_MANAGER__INTERVAL 60000 Interval to check new playbooks - - - - activity_manager:enabled ACTIVITY_MANAGER__ENABLED <code>true</code> Enable/disable the activity manager activity_manager:lock_key ACTIVITY_MANAGER__LOCK_KEY activity_manager_lock Lock key for the manager in Redis - - - - connector_manager:enabled CONNECTOR_MANAGER__ENABLED <code>true</code> Enable/disable the connector manager connector_manager:lock_key CONNECTOR_MANAGER__LOCK_KEY connector_manager_lock Lock key for the manager in Redis connector_manager:works_day_range CONNECTOR_MANAGER__WORKS_DAY_RANGE 7 Days range before considering the works as too old connector_manager:interval CONNECTOR_MANAGER__INTERVAL 10000 Interval to check the state of the works - - - - import_csv_built_in_connector:enabled IMPORT_CSV_CONNECTOR__ENABLED <code>true</code> Enable/disable the csv import connector import_csv_built_in_connector:validate_before_import IMPORT_CSV_CONNECTOR__VALIDATE_BEFORE_IMPORT <code>false</code> Validates the bundle before importing - - - - file_index_manager:enabled FILE_INDEX_MANAGER__ENABLED <code>true</code> Enable/disable the file indexing manager file_index_manager:stream_lock_key FILE_INDEX_MANAGER__STREAM_LOCK file_index_manager_stream_lock Stream lock key for the manager in Redis file_index_manager:interval FILE_INDEX_MANAGER__INTERVAL 60000 Interval to check for new files - - - - indicator_decay_manager:enabled INDICATOR_DECAY_MANAGER__ENABLED <code>true</code> Enable/disable the indicator decay manager indicator_decay_manager:lock_key INDICATOR_DECAY_MANAGER__LOCK_KEY indicator_decay_manager_lock Lock key for the manager in Redis indicator_decay_manager:interval INDICATOR_DECAY_MANAGER__INTERVAL 60000 Interval to check for indicators to update indicator_decay_manager:batch_size INDICATOR_DECAY_MANAGER__BATCH_SIZE 10000 Number of indicators handled by the manager - - - - garbage_collection_manager:enabled GARBAGE_COLLECTION_MANAGER__ENABLED <code>true</code> Enable/disable the trash manager garbage_collection_manager:lock_key GARBAGE_COLLECTION_MANAGER__LOCK_KEY garbage_collection_manager_lock Lock key for the manager in Redis garbage_collection_manager:interval GARBAGE_COLLECTION_MANAGER__INTERVAL 60000 Interval to check for trash elements to delete garbage_collection_manager:batch_size GARBAGE_COLLECTION_MANAGER__BATCH_SIZE 10000 Number of trash elements to delete at once garbage_collection_manager:deleted_retention_days GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS 7 Days after which elements in trash are deleted - - - - telemetry_manager:lock_key TELEMETRY_MANAGER__LOCK_LOCK telemetry_manager_lock Lock key for the manager in Redis <p>Manager's duties</p> <p>A description of each manager's duties is available on a dedicated page.</p>"},{"location":"deployment/configuration/#worker-and-connector","title":"Worker and connector","text":"<p>Can be configured manually using the configuration file <code>config.yml</code> or through environment variables.</p> Parameter Environment variable Default value Description opencti:url OPENCTI_URL The URL of the OpenCTI platform opencti:token OPENCTI_TOKEN A token of an administrator account with bypass capability - - - - mq:use_ssl / / Depending of the API configuration (fetch from API) mq:use_ssl_ca MQ_USE_SSL_CA Path or ca content mq:use_ssl_cert MQ_USE_SSL_CERT Path or cert content mq:use_ssl_key MQ_USE_SSL_KEY Path or key content mq:use_ssl_passphrase MQ_USE_SSL_PASSPHRASE Passphrase for the key certificate mq:use_ssl_reject_unauthorized MQ_USE_SSL_REJECT_UNAUTHORIZED <code>false</code> Reject rabbit self signed certificate"},{"location":"deployment/configuration/#worker-specific-configuration","title":"Worker specific configuration","text":""},{"location":"deployment/configuration/#logging_1","title":"Logging","text":"Parameter Environment variable Default value Description worker:log_level WORKER_LOG_LEVEL info The log level (error, warning, info or debug)"},{"location":"deployment/configuration/#telemetry_1","title":"Telemetry","text":"Parameter Environment variable Default value Description worker:telemetry_enabled WORKER_TELEMETRY_ENABLED false Enable the Prometheus endpoint worker:telemetry_prometheus_port WORKER_PROMETHEUS_TELEMETRY_PORT 14270 Port of the Prometheus endpoint worker:telemetry_prometheus_host WORKER_PROMETHEUS_TELEMETRY_HOST 0.0.0.0 Listen address of the Prometheus endpoint"},{"location":"deployment/configuration/#connector-specific-configuration","title":"Connector specific configuration","text":"<p>For specific connector configuration, you need to check each connector behavior.</p>"},{"location":"deployment/configuration/#elasticsearch_1","title":"ElasticSearch","text":"<p>If you want to adapt the memory consumption of ElasticSearch, you can use these options:</p> <pre><code># Add the following environment variable:\n\"ES_JAVA_OPTS=-Xms8g -Xmx8g\"\n</code></pre> <p>This can be done in configuration file in the <code>jvm.conf</code> file.</p>"},{"location":"deployment/connectors/","title":"Connectors","text":""},{"location":"deployment/connectors/#introduction","title":"Introduction","text":"<p>Connectors list</p> <p>You are looking for the available connectors? The list is in the OpenCTI Ecosystem.</p> <p>Connectors are the cornerstone of the OpenCTI platform and allow organizations to easily ingest, enrich or export data. According to their functionality and use case, they are categorized in the following classes.</p> <p></p>"},{"location":"deployment/connectors/#import","title":"Import","text":"<p>These connectors automatically retrieve information from an external organization, application, or service, and convert it to STIX 2.1 bundles. Then, they import it into OpenCTI using the workers.</p>"},{"location":"deployment/connectors/#enrichment","title":"Enrichment","text":"<p>When a new object is created in the platform or on the user request, it is possible to trigger the internal enrichment connector to lookup and/or search the object in external organizations, applications, or services. If the object is found, the connectors will generate a STIX 2.1 bundle which will increase the level of knowledge about the concerned object.</p> <p></p>"},{"location":"deployment/connectors/#stream","title":"Stream","text":"<p>These connectors connect to a platform live stream and continuously do something with the received events. In most cases, they are used to consume OpenCTI data and insert them in third-party platforms such as SIEMs, XDRs, EDRs, etc. In some cases, stream connectors can also query the external system on a regular basis and act as import connector for instance to gather alerts and sightings related to CTI data and push them to OpenCTI (bi-directional).</p>"},{"location":"deployment/connectors/#import-files","title":"Import files","text":"<p>Information from an uploaded file can be extracted and ingested into OpenCTI. Examples are files attached to a report or a STIX 2.1 file.</p>"},{"location":"deployment/connectors/#export-files","title":"Export files","text":"<p>Information stored in OpenCTI can be extracted into different file formats like .csv or .json (STIX 2.1).</p>"},{"location":"deployment/connectors/#connector-configuration","title":"Connector configuration","text":""},{"location":"deployment/connectors/#connector-users-and-tokens","title":"Connector users and tokens","text":"<p>All connectors have to be able to access the OpenCTI API. To allow this connection, they have 2 mandatory configuration parameters, the <code>OPENCTI_URL</code> and the <code>OPENCTI_TOKEN</code>.</p> <p>Connectors tokens</p> <p>Be careful, we strongly recommend to use a dedicated token for each connector running in the platform. So you have to create a specific user for each of them.</p> <p>Also, if all connectors users can run in with a user belonging to the <code>Connectors</code> group (with the <code>Connector</code> role), the <code>Internal Export Files</code> should be run with a user who is Administrator (with bypass capability) because they impersonate the user requesting the export to avoid data leak.</p> Type Required role Used permissions EXTERNAL_IMPORT Connector Import data with the connector user. INTERNAL_ENRICHMENT Connector Enrich data with the connector user. INTERNAL_IMPORT_FILE Connector Import data with the connector user. INTERNAL_EXPORT_FILE Administrator Export data with the user who requested the export. STREAM Connector Consume the streams with the connector user."},{"location":"deployment/connectors/#parameters","title":"Parameters","text":"<p>In addition to these 2 parameters, connectors have other mandatory parameters that need to be set in order to get them work.</p> <p>Here is an example of a connector <code>docker-compose.yml</code> file: <pre><code>- CONNECTOR_ID=ChangeMe\n- CONNECTOR_TYPE=EXTERNAL_IMPORT\n- CONNECTOR_NAME=MITRE ATT&amp;CK\n- CONNECTOR_SCOPE=identity,attack-pattern,course-of-action,intrusion-set,malware,tool,report\n- CONNECTOR_LOG_LEVEL=info\n</code></pre></p> <p>Here is an example in a connector <code>config.yml</code> file:</p> <pre><code>connector:\n  id: 'ChangeMe'\n  type: 'EXTERNAL_IMPORT'\n  name: 'MITRE ATT&amp;CK'\n  scope: 'identity,attack-pattern,course-of-action,intrusion-set,malware,tool,report'\n  log_level: 'info'\n</code></pre>"},{"location":"deployment/connectors/#advanced-parameters","title":"Advanced parameters","text":"<p>By default, connector are connecting to <code>RabbitMQ</code> using parameters and credentials directly given by the API during the connector registration process. In some cases, you may need to override them.</p> <pre><code>- MQ_HOST=rabbit.mydomain.com\n- MQ_PORT=5672\n- MQ_VHOST=/\n- MQ_USE_SSL=false\n- MQ_USER=guest\n- MQ_PASS=guest\n</code></pre> <p>Here is an example in a connector <code>config.yml</code> file:</p> <pre><code>mq:\n  host: 'rabbit.mydomain.com'\n  port: '5672'\n  use_ssl: false\n  user: 'guest'\n  pass: 'guest'\n</code></pre>"},{"location":"deployment/connectors/#networking","title":"Networking","text":"<p>Be aware that all connectors are reaching RabbitMQ based the RabbitMQ configuration provided by the OpenCTI platform. The connector must be able to reach RabbitMQ on the specified hostname and port. If you have a specific Docker network configuration, please be sure to adapt your <code>docker-compose.yml</code> file in such way that the connector container gets attached to the OpenCTI Network, e.g.:</p> <pre><code>networks:\n  default:\n    external: true\n    name: opencti-docker_default\n</code></pre> <p></p>"},{"location":"deployment/connectors/#connector-token","title":"Connector token","text":""},{"location":"deployment/connectors/#create-the-user","title":"Create the user","text":"<p>As mentioned previously, it is strongly recommended to run each connector with its own user. The <code>Internal Export File</code> connectors should be launched with a user that belongs to a group which has an \u201cAdministrator\u201d role (with bypass all capabilities enabled).</p> <p>By default, in platform, a group named \"Connectors\" already exists. So just create a new user with the name <code>[C] Name of the connector</code> in Settings &gt; Security &gt; Users.</p> <p></p>"},{"location":"deployment/connectors/#put-the-user-in-the-group","title":"Put the user in the group","text":"<p>Just go to the user you have just created and add it to the <code>Connectors</code> group.</p> <p></p> <p>Then just get the token of the user displayed in the interface.</p> <p></p>"},{"location":"deployment/connectors/#docker-activation","title":"Docker activation","text":"<p>You can either directly run the Docker image of connectors or add them to your current <code>docker-compose.yml</code> file.</p>"},{"location":"deployment/connectors/#add-a-connector-to-your-deployment","title":"Add a connector to your deployment","text":"<p>For instance, to enable the MISP connector, you can add a new service to your <code>docker-compose.yml</code> file:</p> <pre><code>  connector-misp:\n    image: opencti/connector-misp:latest\n    environment:\n      - OPENCTI_URL=http://localhost\n      - OPENCTI_TOKEN=ChangeMe\n      - CONNECTOR_ID=ChangeMe\n      - CONNECTOR_TYPE=EXTERNAL_IMPORT\n      - CONNECTOR_NAME=MISP\n      - CONNECTOR_SCOPE=misp\n      - CONNECTOR_LOG_LEVEL=info\n      - MISP_URL=http://localhost # Required\n      - MISP_KEY=ChangeMe # Required\n      - MISP_SSL_VERIFY=False # Required\n      - MISP_CREATE_REPORTS=True # Required, create report for MISP event\n      - MISP_REPORT_CLASS=MISP event # Optional, report_class if creating report for event\n      - MISP_IMPORT_FROM_DATE=2000-01-01 # Optional, import all event from this date\n      - MISP_IMPORT_TAGS=opencti:import,type:osint # Optional, list of tags used for import events\n      - MISP_INTERVAL=1 # Required, in minutes\n    restart: always\n</code></pre>"},{"location":"deployment/connectors/#launch-a-standalone-connector","title":"Launch a standalone connector","text":"<p>To launch standalone connector, you can use the <code>docker-compose.yml</code> file of the connector itself. Just download the latest release and start the connector:</p> <pre><code>$ wget https://github.com/OpenCTI-Platform/connectors/archive/{RELEASE_VERSION}.zip\n$ unzip {RELEASE_VERSION}.zip\n$ cd connectors-{RELEASE_VERSION}/misp/\n</code></pre> <p>Change the configuration in the <code>docker-compose.yml</code> according to the parameters of the platform and of the targeted service. Then launch the connector:</p> <pre><code>$ docker-compose up\n</code></pre>"},{"location":"deployment/connectors/#manual-activation","title":"Manual activation","text":"<p>If you want to manually launch connector, you just have to install Python 3 and pip3 for dependencies:</p> <pre><code>$ apt install python3 python3-pip\n</code></pre> <p>Download the release of the connectors:</p> <pre><code>$ wget &lt;https://github.com/OpenCTI-Platform/connectors/archive/{RELEASE_VERSION}.zip&gt;\n$ unzip {RELEASE_VERSION}.zip\n$ cd connectors-{RELEASE_VERSION}/misp/src/\n</code></pre> <p>Install dependencies and initialize the configuration:</p> <pre><code>$ pip3 install -r requirements.txt\n$ cp config.yml.sample config.yml\n</code></pre> <p>Change the <code>config.yml</code> content according to the parameters of the platform and of the targeted service and launch the connector:</p> <pre><code>$ python3 misp.py\n</code></pre>"},{"location":"deployment/connectors/#connectors-status","title":"Connectors status","text":"<p>The connector status can be displayed in the dedicated section of the platform available in Data &gt; Ingestion &gt; Connectors. You will be able to see the statistics of the RabbitMQ queue of the connector:</p> <p></p> <p>Problem</p> <p>If you encounter problems deploying OpenCTI or connectors, you can consult the troubleshooting page page.</p>"},{"location":"deployment/installation/","title":"Installation","text":"<p>All components of OpenCTI are shipped both as Docker images and manual installation packages.</p> <p>Production deployment</p> <p>For production deployment, we recommend to deploy all components in containers, including dependencies, using native cloud services or orchestration systems such as Kubernetes.</p> <p>To have more details about deploying OpenCTI and its dependencies in cluster mode, please read the dedicated section.</p> <ul> <li> <p> Use Docker</p> <p>Deploy OpenCTI using Docker and the default <code>docker-compose.yml</code> provided in the docker.</p> <p> Setup</p> </li> <li> <p> Manual installation</p> <p>Deploy dependencies and launch the platform manually using the packages released in the GitHub releases.</p> <p> Explore</p> </li> </ul>"},{"location":"deployment/installation/#using-docker","title":"Using Docker","text":"<p>OpenCTI can be deployed using the docker-compose command.</p> <p>Deploy FIPS 140-2 compliant components</p> <p>We provide FIPS 140-2 compliant images. Please read the dedicated documentation to understand how to deploy OpenCTI in FIPS-compliant mode.</p>"},{"location":"deployment/installation/#pre-requisites","title":"Pre-requisites","text":"<p> Linux</p> <pre><code>sudo apt install docker-compose\n</code></pre> <p> Windows and MacOS</p> <p>Just download the appropriate Docker for Desktop version for your operating system.</p>"},{"location":"deployment/installation/#clone-the-repository","title":"Clone the repository","text":"<p>Docker helpers are available in the Docker GitHub repository.</p> <pre><code>mkdir -p /path/to/your/app &amp;&amp; cd /path/to/your/app\ngit clone https://github.com/OpenCTI-Platform/docker.git\ncd docker\n</code></pre>"},{"location":"deployment/installation/#configure-the-environment","title":"Configure the environment","text":"<p>ElasticSearch / OpenSearch configuration</p> <ul> <li>We strongly recommend that you add the following ElasticSearch / OpenSearch parameter:</li> </ul> <pre><code>thread_pool.search.queue_size=5000\n</code></pre> <ul> <li>Check the OpenCTI Integration User Permissions in OpenSearch/ElasticSearch for detailed information about the user permissions required for the OpenSearch/ElasticSearch integration.</li> </ul> <p>Before running the <code>docker-compose</code> command, the <code>docker-compose.yml</code> file should be configured. By default, the <code>docker-compose.yml</code> file is using environment variables available in the file <code>.env.sample</code>.</p> <p>You can either rename the file <code>.env.sample</code> as <code>.env</code> and enter the values or just directly edit the <code>docker-compose.yml</code> with the values for your environment.</p> <p>Configuration static parameters</p> <p>The complete list of available static parameters is available in the configuration section.</p> <p>Here is an example to quickly generate the <code>.env</code> file under Linux, especially all the default UUIDv4:</p> <pre><code>sudo apt install -y jq\ncd ~/docker\n(cat &lt;&lt; EOF\nOPENCTI_ADMIN_EMAIL=admin@opencti.io\nOPENCTI_ADMIN_PASSWORD=ChangeMePlease\nOPENCTI_ADMIN_TOKEN=$(cat /proc/sys/kernel/random/uuid)\nOPENCTI_BASE_URL=http://localhost:8080\nMINIO_ROOT_USER=$(cat /proc/sys/kernel/random/uuid)\nMINIO_ROOT_PASSWORD=$(cat /proc/sys/kernel/random/uuid)\nRABBITMQ_DEFAULT_USER=guest\nRABBITMQ_DEFAULT_PASS=guest\nELASTIC_MEMORY_SIZE=4G\nCONNECTOR_HISTORY_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_STIX_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_CSV_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_IMPORT_FILE_STIX_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_EXPORT_FILE_TXT_ID=$(cat /proc/sys/kernel/random/uuid)\nCONNECTOR_IMPORT_DOCUMENT_ID=$(cat /proc/sys/kernel/random/uuid)\nSMTP_HOSTNAME=localhost\nEOF\n) &gt; .env\n</code></pre> <p>If your <code>docker-compose</code> deployment does not support <code>.env</code> files, just export all environment variables before launching the platform:</p> <pre><code>export $(cat .env | grep -v \"#\" | xargs)\n</code></pre> <p>As OpenCTI has a dependency on ElasticSearch, you have to set <code>vm.max_map_count</code> before running the containers, as mentioned in the ElasticSearch documentation.</p> <pre><code>sudo sysctl -w vm.max_map_count=1048575\n</code></pre> <p>To make this parameter persistent, add the following to the end of your <code>/etc/sysctl.conf</code>:</p> <pre><code>vm.max_map_count=1048575\n</code></pre>"},{"location":"deployment/installation/#persist-data","title":"Persist data","text":"<p>The default for OpenCTI data is to be persistent.</p> <p>In <code>docker-compose.yml</code>, you will find the list of necessary persistent volumes for the dependencies at the end:</p> <pre><code>volumes:\n  esdata:     # ElasticSearch data\n  s3data:     # S3 bucket data\n  redisdata:  # Redis data\n  amqpdata:   # RabbitMQ data\n</code></pre>"},{"location":"deployment/installation/#run-opencti","title":"Run OpenCTI","text":""},{"location":"deployment/installation/#using-single-node-docker","title":"Using single node Docker","text":"<p>After changing your <code>.env</code> file run <code>docker-compose</code> in detached (-d) mode:</p> <pre><code>sudo systemctl start docker.service\n# Run docker-compose in detached\ndocker-compose up -d\n</code></pre>"},{"location":"deployment/installation/#using-docker-swarm","title":"Using Docker swarm","text":"<p>In order to have the best experience with Docker, we recommend using the Docker stack feature. In this mode you will have the capacity to easily scale your deployment.</p> <pre><code># If your virtual machine is not a part of a Swarm cluster, please use:\ndocker swarm init\n</code></pre> <p>Put your environment variables in <code>/etc/environment</code>:</p> <pre><code># If you already exported your variables to .env from above:\nsudo cat .env &gt;&gt; /etc/environment\nsudo bash -c 'cat .env &gt;&gt; /etc/environment'\nsudo docker stack deploy --compose-file docker-compose.yml opencti\n</code></pre> <p>Installation done</p> <p>You can now go to http://localhost:8080 and log in with the credentials configured in your environment variables.</p>"},{"location":"deployment/installation/#manual-installation","title":"Manual installation","text":""},{"location":"deployment/installation/#prerequisites","title":"Prerequisites","text":""},{"location":"deployment/installation/#installation-of-dependencies","title":"Installation of dependencies","text":"<p>You have to install all the needed dependencies for the main application and the workers. The example below is for Debian-based systems:</p> <pre><code>sudo apt-get update\nsudo apt-get install build-essential nodejs npm python3 python3-pip python3-dev\n</code></pre>"},{"location":"deployment/installation/#download-the-application-files","title":"Download the application files","text":"<p>First, you have to download and extract the latest release file. Then select the version to install depending of your operating system:</p> <p>For Linux:</p> <ul> <li>If your OS supports libc (Ubuntu, Debian, ...) you have to install the <code>opencti-release_{RELEASE_VERSION}.tar.gz</code> version.</li> <li>If your OS uses musl (Alpine, ...) you have to install the <code>opencti-release-{RELEASE_VERSION}_musl.tar.gz</code> version.</li> </ul> <p>For Windows:</p> <p>We don't provide any Windows release for now. However it is still possible to check the code out, manually install the dependencies and build the software.</p> <pre><code>mkdir /path/to/your/app &amp;&amp; cd /path/to/your/app\nwget &lt;https://github.com/OpenCTI-Platform/opencti/releases/download/{RELEASE_VERSION}/opencti-release-{RELEASE_VERSION}.tar.gz&gt;\ntar xvfz opencti-release-{RELEASE_VERSION}.tar.gz\n</code></pre>"},{"location":"deployment/installation/#install-the-main-platform","title":"Install the main platform","text":""},{"location":"deployment/installation/#configure-the-application","title":"Configure the application","text":"<p>The main application has just one JSON configuration file to change and a few Python modules to install</p> <pre><code>cd opencti\ncp config/default.json config/production.json\n</code></pre> <p>Change the config/production.json file according to your configuration of ElasticSearch, Redis, RabbitMQ and S3 bucket as well as default credentials (the <code>ADMIN_TOKEN</code> must be a valid UUID).</p>"},{"location":"deployment/installation/#install-the-python-modules","title":"Install the Python modules","text":"<pre><code>cd src/python\npip3 install -r requirements.txt\ncd ../..\n</code></pre>"},{"location":"deployment/installation/#start-the-application","title":"Start the application","text":"<p>The application is just a NodeJS process, the creation of the database schema and the migration will be done at starting.</p> <p>Please verify that yarn version is greater than 4 and node version is greater or equals to v19. Please note that some Node.js version are outdated in linux package manager, you can download a recent one in https://nodejs.org/en/download or alternatively nvm can help to chose a recent version of Node.js https://github.com/nvm-sh/nvm</p> <pre><code>yarn --version\n#4.1.0\nnode --version\n#v20.11.1\n</code></pre> <p>Once Node.js is setup, you can build and run with (from inside <code>opencti</code> folder): <pre><code>yarn install\nyarn build\nyarn serv\n</code></pre></p> <p>The default username and password are those you have put in the <code>config/production.json</code> file.</p>"},{"location":"deployment/installation/#install-the-worker","title":"Install the worker","text":"<p>The OpenCTI worker is used to write the data coming from the RabbitMQ messages broker.</p>"},{"location":"deployment/installation/#configure-the-worker","title":"Configure the worker","text":"<pre><code>cd worker\npip3 install -r requirements.txt\ncp config.yml.sample config.yml\n</code></pre> <p>Change the config.yml file according to your OpenCTI token.</p>"},{"location":"deployment/installation/#start-as-many-workers-as-you-need","title":"Start as many workers as you need","text":"<pre><code>python3 worker.py &amp;\npython3 worker.py &amp;\n</code></pre> <p>Installation done</p> <p>You can now go to http://localhost:4000 and log in with the credentials configured in your <code>production.json</code> file.</p>"},{"location":"deployment/installation/#community-contributions","title":"Community contributions","text":""},{"location":"deployment/installation/#terraform","title":"Terraform","text":"<ul> <li> <p> Multi-clouds Terraform scripts</p> <p>This repository is here to provide you with a quick and easy way to deploy an OpenCTI instance in the cloud (AWS, Azure, or GCP).</p> <p> GitHub Respository</p> </li> <li> <p> AWS Advanced Terraform scripts</p> <p>A Terraform deployment of OpenCTI designed to make use of native AWS Resources (where feasible). This includes AWS ECS Fargate, AWS OpenSearch, etc.</p> <p> GitHub Repository</p> </li> </ul>"},{"location":"deployment/installation/#helm-charts","title":"Helm Charts","text":"<ul> <li> <p> Kubernetes Helm Charts</p> <p>OpenCTI Helm Charts for Kubernetes with a global configuration file. More information how to deploy here on basic installation and examples.</p> <p> GitHub Repository</p> </li> </ul>"},{"location":"deployment/installation/#deploy-behind-a-reverse-proxy","title":"Deploy behind a reverse proxy","text":"<p>If you want to use OpenCTI behind a reverse proxy with a context path, like <code>https://domain.com/opencti</code>, please change the <code>base_path</code> static parameter.</p> <ul> <li><code>APP__BASE_PATH=/opencti</code></li> </ul> <p>By default OpenCTI use websockets so don't forget to configure your proxy for this usage, an example with <code>Nginx</code>:</p> <pre><code>location / {\n    proxy_cache                 off;\n    proxy_buffering             off;\n    proxy_http_version          1.1;\n    proxy_set_header Upgrade    $http_upgrade;\n    proxy_set_header Connection \"upgrade\";\n    proxy_set_header Host       $host;\n    chunked_transfer_encoding   off;\n    proxy_pass                  http://YOUR_UPSTREAM_BACKEND;\n  }\n</code></pre>"},{"location":"deployment/installation/#additional-memory-information","title":"Additional memory information","text":""},{"location":"deployment/installation/#platform","title":"Platform","text":"<p>OpenCTI platform is based on a NodeJS runtime, with a memory limit of 8GB by default. If you encounter <code>OutOfMemory</code> exceptions, this limit could be changed:</p> <pre><code>- NODE_OPTIONS=--max-old-space-size=8096\n</code></pre>"},{"location":"deployment/installation/#workers-and-connectors","title":"Workers and connectors","text":"<p>OpenCTI workers and connectors are Python processes. If you want to limit the memory of the process, we recommend to directly use Docker to do that. You can find more information in the official Docker documentation.</p>"},{"location":"deployment/installation/#elasticsearch","title":"ElasticSearch","text":"<p>ElasticSearch is also a JAVA process. In order to setup the JAVA memory allocation, you can use the environment variable <code>ES_JAVA_OPTS</code>. You can find more information in the official ElasticSearch documentation.</p>"},{"location":"deployment/installation/#redis","title":"Redis","text":"<p>Redis has a very small footprint on keys but will consume memory for the stream. By default the size of the stream is limited to 2 millions which represents a memory footprint around <code>8 GB</code>. You can find more information in the Redis docker hub.</p>"},{"location":"deployment/installation/#minio-s3-bucket","title":"MinIO / S3 Bucket","text":"<p>MinIO is a small process and does not require a high amount of memory. More information are available for Linux here on the Kernel tuning guide.</p>"},{"location":"deployment/installation/#rabbitmq","title":"RabbitMQ","text":"<p>The RabbitMQ memory configuration can be find in the RabbitMQ official documentation. RabbitMQ will consumed memory until a specific threshold, therefore it should be configure along with the Docker memory limitation.</p>"},{"location":"deployment/integrations/","title":"Integrations","text":""},{"location":"deployment/integrations/#introduction","title":"Introduction","text":"<p>OpenCTI supports multiple ways to integrate with other systems which do not have native connectors or plugins to the platform. Here are the technical features available to ease the connection and the integration of the platform with other applications.</p> <p>Connectors list</p> <p>If you are looking for the list of OpenCTI connectors or native integration, please check the OpenCTI Ecosystem.</p>"},{"location":"deployment/integrations/#native-feeds-and-streams","title":"Native feeds and streams","text":"<p>To ease integrations with other products, OpenCTI has built-in capabilities to deliver the data to third-parties.</p>"},{"location":"deployment/integrations/#csv-feeds","title":"CSV Feeds","text":"<p>It is possible to create as many CSV feeds as needed, based on filters and accessible in HTTP. CSV feeds are available in Data &gt; Data sharing &gt; CSV deeds.</p> <p>When creating a CSV feed, you need to select one or multiple types of entities to make available. Then, you must assign a field (of an entity type) to each column in the CSV:</p> <p></p> <p>Details</p> <p>For more information about CSV feeds, filters and configuration, please check the Native feeds page.</p>"},{"location":"deployment/integrations/#taxii-collections","title":"TAXII collections","text":"<p>Most of the modern cybersecurity systems such as SIEMs, EDRs, XDRs and even firewalls supports the TAXII protocol which is basically a paginated HTTP STIX feed. OpenCTI implements a TAXII 2.1 server with the ability to create as many TAXII collections as needed in Data &gt; Data sharing &gt; TAXII Collections.</p> <p>TAXII collections are a sub-selection of the knowledge available in the platform and rely on filters. For instance, it is possible to create TAXII collections for pieces of malware with a given label, for indicators with a score greater than n, etc.</p> <p></p>"},{"location":"deployment/integrations/#live-streams","title":"Live Streams","text":"<p>After implementing CSV feeds and TAXII collections, we figured out that those 2 stateless APIs are definitely not enough when it comes to tackle advanced information sharing challenges such as:</p> <ul> <li>Real time transmission of the information (i.e. avoid hundreds of systems to pull data every 5 minutes).</li> <li>Dependencies resolution (i.e. an intrusion created by an organization but the organization is not in the TAXII collection).</li> <li>Partial update for huge entities such as report (i.e. just having the update event).</li> <li>Delete events when necessary (i.e. to handle indicators expiration in third party systems for instance).</li> </ul> <p>That's why we've developed the live streams. They are available in Data &gt; Data sharing &gt; Live streams. As TAXII collections, it is possible to create as many streams as needed using filters.</p> <p></p> <p>Streams implement the HTTP SSE (Server-sent events) protocol and give applications the possibility to consume a real time pure STIX 2.1 stream. Stream connectors in the OpenCTI Ecosystem are using live streams to consume data and do something such as create / update / delete information in SIEMs, XDRs, etc.</p>"},{"location":"deployment/integrations/#authentication","title":"Authentication","text":"<p>For all previously explained capabilities, as they are over the HTTP protocol, 3 authentication mechanisms are available to consume them.</p> <ol> <li> <p>Using a bearer header with your OpenCTI API key</p> <pre><code>Authorization: Bearer a17bc103-8420-4208-bd53-e1f80845d15f\n</code></pre> <p>API Key</p> <p>Your API key can be found in your profile available clicking on the top right icon.</p> </li> <li> <p>Using basic authentication</p> <pre><code>Username: Your platform username\nPassword: Your plafrom password\nAuthorization: Basic c2FtdWVsLmhhc3NpbmVBZmlsaWdyYW4uaW86TG91aXNlMTMwNCM=\n</code></pre> </li> <li> <p>Using client certificate authentication</p> <p>To know how to configure the client certificate authentication, please consult the authentication configuration section.</p> </li> </ol>"},{"location":"deployment/integrations/#api-and-libraries","title":"API and libraries","text":""},{"location":"deployment/integrations/#graphql-api","title":"GraphQL API","text":"<p>To allow analysts and developers to implement more custom or complex use cases, a full GraphQL API is available in the application on the <code>/graphql</code> endpoint.</p> <p>The API can be queried using various GraphQL client such as Postman but you can leverage any HTTP client to forge GraphQL queries using <code>POST</code> methods.</p>"},{"location":"deployment/integrations/#authentication_1","title":"Authentication","text":"<p>The API authentication can be performed using the token of a user and a classic Authorization header:</p> <pre><code>Content-Type: application/json\nAuthorization: Bearer 6b6554c4-bb2c-4c80-9cd3-30288c8bf424\n</code></pre>"},{"location":"deployment/integrations/#playground","title":"Playground","text":"<p>The playground is available on the <code>/graphql</code> endpoint. A link button is also available in the profile of your user.</p> <p></p> <p>All the schema documentation is directly available in the playground.</p> <p></p> <p>If you already logged to OpenCTI with the same browser you should be able to directly do some requests. If you are not authenticated or want to authenticate only through the playground you can use a header configuration using your profile token</p> <p>Example of configuration (bottom left of the playground):</p> <p></p> <p>Additional GraphQL documentation</p> <p>To find out more about GraphQL and the playground, you can find two additional documentation pages: the GraphQL API page and the GraphQL playground page.</p>"},{"location":"deployment/integrations/#python-library","title":"Python library","text":"<p>Since not everyone is familiar with GraphQL APIs, we've developed a Python library to ease the interaction with it. The library is pretty easy to use. To initiate the client:</p> <pre><code># coding: utf-8\n\nfrom pycti import OpenCTIApiClient\n\n# Variables\napi_url = \"http://opencti:4000\"\napi_token = \"bfa014e0-e02e-4aa6-a42b-603b19dcf159\"\n\n# OpenCTI initialization\nopencti_api_client = OpenCTIApiClient(api_url, api_token)\n</code></pre> <p>Then just use the available helpers: <pre><code># Search for malware with the keyword \"windows\"\nmalwares = opencti_api_client.malware.list(search=\"windows\")\n\n# Print\nprint(malwares)\n</code></pre></p> <p>Details</p> <p>For more detailed information about the Python library, please read the dedicated section.</p>"},{"location":"deployment/managers/","title":"Platform managers","text":"<p>Platform managers are background components that perform various tasks to support some important functionalities in the platform.</p> <p>Here is a list of all the managers on the platform:</p>"},{"location":"deployment/managers/#rules-engine","title":"Rules engine","text":"<p>Allows users to execute pre-defined actions based on the data and events in the platform.</p> <p>These rules are accessible in Settings &gt; Customization &gt; Rules engine.</p> <p>The rules engine is designed to help users automate and streamline their cyber threat intelligence processes.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#history-manager","title":"History manager","text":"<p>This manager keeps tracks of user/connector interactions on entities in the platform.</p> <p>It is designed to help users audit and understand the evolution of their CTI data.</p>"},{"location":"deployment/managers/#activity-manager","title":"Activity manager","text":"<p>The activity manager in OpenCTI is a component that monitors and logs the user actions in the platform such as login, settings update, and user activities if configured (read, udpate, etc.).</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#background-task-manager","title":"Background task manager","text":"<p>Is a component that handles the execution of tasks, such as importing data, exporting data and mass operations.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#expiration-scheduler","title":"Expiration scheduler","text":"<p>The expiration scheduler is responsible for monitoring expired elements in the platform. It cancels the access rights of expired user accounts and revokes expired indicators from the platform.</p>"},{"location":"deployment/managers/#synchronization-manager","title":"Synchronization manager","text":"<p>The synchronization manager enables the data sharing between multiple OpenCTI platforms.  It allows the user to create and configure synchronizers which are processes that connect to the live streams of remote OpenCTI platforms and import the data into the local platform. </p>"},{"location":"deployment/managers/#retention-manager","title":"Retention manager","text":"<p>The retention manager is a component that allows the user to define rules to help delete data in OpenCTI that is no longer relevant or useful. This helps to optimize the performance and storage of the OpenCTI platform and ensures the quality and accuracy of the data.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#notification-manager","title":"Notification manager","text":"<p>The notification manager is a component that allows the user to customize and receive alerts about events/changes in the platform.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#ingestion-manager","title":"Ingestion manager","text":"<p>The ingestion manager in OpenCTI is a component that manages the ingestion of data from RSS and TAXII feeds.</p>"},{"location":"deployment/managers/#playbook-manager","title":"Playbook manager","text":"<p>The playbook manager handles the automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform.</p> <p>Please read the Playbook automation page to get more information.</p>"},{"location":"deployment/managers/#file-index-manager","title":"File index manager","text":"<p>The file indexing manager extracts and indexes the text content of the files, and stores it in the database. It allows users to search for text content within files uploaded to the platform.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#indicator-decay-manager","title":"Indicator decay manager","text":"<p>The indicator decay manager allows to update indicators score automatically based on configured decay rules.</p> <p>More information can be found here.</p>"},{"location":"deployment/managers/#trash-manager","title":"Trash manager","text":"<p>The trash manager is responsible to delete permanently elements stored in the trash after a specified period of time (7 days by default).</p>"},{"location":"deployment/managers/#filigran-telemetry-manager","title":"Filigran telemetry manager","text":"<p>The telemetry manager collects periodically statistical data about platform usage.</p> <p>More information about data telemetry can be found here.</p>"},{"location":"deployment/map/","title":"Deploy on-premise map server with OpenCTI styles","text":""},{"location":"deployment/map/#introduction","title":"Introduction","text":"<p>The OpenStreetMap tiles for the planet will take 80GB. Here are the instructions to deploy a local OpenStreetMap server with the OpenCTI styles.</p>"},{"location":"deployment/map/#create-directory-for-the-data-and-upload-planet-data","title":"Create directory for the data and upload planet data","text":"<p>When you will launch the map server container, it will be necessary to mount a volume with the planet tiles data. Just create the directory for the data.</p> <pre><code>mkdir /var/YOUR_DATA_DIR\n</code></pre> <p>We have hosted the free-to-use planet tiles, just download the planet data from filigran.io.</p> <pre><code>wget https://filigran.io/app/uploads/maptiler-osm-2020-02-10-v3.11-planet.mbtiles\n</code></pre> <p>Put the file <code>maptiler-osm-2020-12-14-v3.11-planet.mbtiles</code> in the data directory:</p> <pre><code>cp maptiler-osm-2020-12-14-v3.11-planet.mbtiles /var/YOUR_DATA_DIR/\n</code></pre>"},{"location":"deployment/map/#start-docker","title":"Start Docker","text":"<p>Replace the port 80 by the port you would like to expose. Inside the Docker, the map server listen on the port 80.</p> <pre><code>docker run -d --restart always -v /var/YOUR_DATA_DIR:/data -p 80:80 klokantech/openmaptiles-server:latest \n</code></pre>"},{"location":"deployment/map/#configure","title":"Configure","text":"<p>Download on your computer the OpenCTI JSON styles (you will have to upload it through the web UI later).</p> <ul> <li>OpenCTI Map Dark mode style (filigran-dark2.json)</li> <li>OpenCTI Map Light mode style (filigran-light2.json)</li> </ul> <p>Now, you can access to the map server, you should see the following page:</p> <p></p> <p>On the next page, you should see the existing data:</p> <p></p> <p>On the next page, click on \"Advanced Options\":</p> <p></p> <p>Upload the <code>filigran-dark2.json</code> and <code>filigran-light2.json</code> files:</p> <p></p> <p>Save and run the server with default parameters:</p> <p></p>"},{"location":"deployment/map/#opencti-parameters","title":"OpenCTI Parameters","text":"<p>Once the server is running, you should see the list of available styles:</p> <p></p> <p>Click on \"Viewer\", and take the URL:</p> <p>\ud83d\udc49 http:/YOUR_URL/styles/{ID}/....</p> <p>In the OpenCTI configuration, just put:</p> Parameter Environment variable Value Description app:map_tile_server_dark APP__MAP_TILE_SERVER_DARK http://{YOUR_MAP_SERVER}/styles/{ID_DARK}/{z}/{x}/{y}.png The address of the OpenStreetMap provider with dark theme style app:map_tile_server_light APP__MAP_TILE_SERVER_LIGHT http://{YOUR_MAP_SERVER}/styles/{ID_LIGHT}/{z}/{x}/{y}.png The address of the OpenStreetMap provider with light theme style <p>You're good to go!</p>"},{"location":"deployment/overview/","title":"Overview","text":"<p>Before starting the installation, let's discover how OpenCTI is working, which dependencies are needed and what are the minimal requirements to deploy it in production.</p>"},{"location":"deployment/overview/#architecture","title":"Architecture","text":"<p>The OpenCTI platform relies on several external databases and services in order to work.</p> <p></p>"},{"location":"deployment/overview/#platform","title":"Platform","text":"<p>The platform is the central part of the OpenCTI technological stack. It allows users to access to the user interface but also provides the GraphQL API used by connectors and workers to insert data. In the context of a production deployment, you may need to scale horizontally and launch multiple platforms behind a load balancer connected to the same databases (ElasticSearch, Redis, S3, RabbitMQ).</p>"},{"location":"deployment/overview/#workers","title":"Workers","text":"<p>The workers are standalone Python processes consuming messages from the RabbitMQ broker in order to do asynchronous write queries. You can launch as many workers as you need to increase the write performances. At some point, the write performances will be limited by the throughput of the ElasticSearch database cluster.</p> <p>Number of workers</p> <p>If you need to increase performances, it is better to launch more platforms to handle worker queries. The recommended setup is to have at least one platform for 3 workers (ie. 9 workers distributed over 3 platforms).</p>"},{"location":"deployment/overview/#connectors","title":"Connectors","text":"<p>The connectors are third-party pieces of software (Python processes) that can play five different  roles on the platform:</p> Type Description Examples EXTERNAL_IMPORT Pull data from remote sources, convert it to STIX2 and insert it on the OpenCTI platform. MITRE Datasets, MISP, CVE, AlienVault, Mandiant, etc. INTERNAL_ENRICHMENT Listen for new OpenCTI entities or users requests, pull data from remote sources to enrich. Shodan, DomainTools, IpInfo, etc. INTERNAL_IMPORT_FILE Extract data from files uploaded on OpenCTI trough the UI or the API. STIX 2.1, PDF, Text, HTML, etc. INTERNAL_EXPORT_FILE Generate export from OpenCTI data, based on a single object or a list. STIX 2.1, CSV, PDF, etc. STREAM Consume a platform data stream an do something with events. Splunk, Elastic Security, Q-Radar, etc. <p>List of connectors</p> <p>You can find all currently available connectors in the OpenCTI Ecosystem.</p>"},{"location":"deployment/overview/#infrastructure-requirements","title":"Infrastructure requirements","text":""},{"location":"deployment/overview/#dependencies","title":"Dependencies","text":"Component Version CPU RAM Disk type Disk space ElasticSearch / OpenSearch &gt;= 8.0 / &gt;= 2.9 2 cores \u2265 8GB SSD \u2265 16GB Redis &gt;= 7.1 1 core \u2265 1GB SSD \u2265 16GB RabbitMQ &gt;= 3.11 1 core \u2265 512MB Standard \u2265 2GB S3 / MinIO &gt;= RELEASE.2023-02 1 core \u2265 128MB SSD \u2265 16GB"},{"location":"deployment/overview/#platform_1","title":"Platform","text":"Component CPU RAM Disk type Disk space OpenCTI Core 2 cores \u2265 8GB None (stateless) - Worker(s) 1 core \u2265 128MB None (stateless) - Connector(s) 1 core \u2265 128MB None (stateless) - <p>Clustering</p> <p>To have more details about deploying OpenCTI and its dependencies in cluster mode, please read the dedicated section.</p>"},{"location":"deployment/resources/","title":"Other resources","text":""},{"location":"deployment/resources/#introduction","title":"Introduction","text":"<p>OpenCTI is an open and modular platform. A lot of connectors, plugins and clients  are created by Filigran and by the community. You can find here other resources available to complete your OpenCTI journey.</p>"},{"location":"deployment/resources/#videos-training","title":"Videos &amp; training","text":"<ul> <li> <p> YouTube channel</p> <p>Watch demonstration videos, use case explanations, customers and community testimonies, and past webinars.</p> <p> Watch</p> </li> <li> <p> Training courses</p> <p>Empower your journey with OpenCTI training courses for both analyst and  administrators, and get your certificate.</p> <p> Learn</p> </li> </ul>"},{"location":"deployment/resources/#articles-news","title":"Articles &amp; news","text":"<ul> <li> <p> Blog articles</p> <p>Read posts written by both Filigran teams and community members about OpenCTI features and use cases.</p> <p> Read</p> </li> <li> <p> Newsletters</p> <p>Subscribe to Filigran newsletters to get informed about the latest evolutions of our product ecosystems.</p> <p> Subscribe</p> </li> </ul>"},{"location":"deployment/resources/#analysis","title":"Analysis","text":"<ul> <li> <p> Verticalized threat landscapes</p> <p>Access to monthly sectorial analysis from our experts team based on knowledge and data collected by our partners.</p> <p> Consult</p> </li> <li> <p> Case studies</p> <p>Explore the Filigran case studies about stories and usages of the platform  among our communities and customers.</p> <p> Download</p> </li> </ul>"},{"location":"deployment/rollover/","title":"Indices and rollover policies","text":"<p>Default rollover policies</p> <p>Since OpenCTI 5.9.0, rollover policies are automatically created when the platform is initialized for the first time. If your platform has been initialized using an older version of OpenCTI or if you would like to understand (and customize) rollover policies please read the following documentation.</p>"},{"location":"deployment/rollover/#introduction","title":"Introduction","text":"<p>ElasticSearch and OpenSearch both support rollover on indices. OpenCTI has been designed to be able to use aliases for indices and so support very well index lifecycle policies. Thus, by default OpenCTI initialized indices with a suffix <code>-00001</code> and use wildcard to query indices. When rollover policies are implemented (default starting OCTI 5.9.X if you initialized your platform at this version), indices are splitted to keep a reasonable volume of data in shards.</p> <p></p>"},{"location":"deployment/rollover/#opencti-integration-user-permissions-in-opensearchelasticsearch","title":"OpenCTI Integration User Permissions in OpenSearch/ElasticSearch","text":"<ul> <li> <p>Index Permissions</p> <ul> <li>Patterns: <code>opencti*</code> (Dependent on the parameter elasticsearch:index_prefix value)</li> <li>Permissions: <code>indices_all</code></li> </ul> </li> <li> <p>Cluster Permissions</p> <ul> <li><code>cluster_composite_ops_ro</code></li> <li><code>cluster_manage_index_templates</code></li> <li><code>cluster:admin/ingest/pipeline/put</code></li> <li><code>cluster:admin/opendistro/ism/policy/write</code></li> <li><code>cluster:monitor/health</code></li> <li><code>cluster:monitor/main</code></li> <li><code>cluster:monitor/state</code></li> <li><code>indices:admin/index_template/put</code></li> <li><code>indices:data/read/scroll/clear</code></li> <li><code>indices:data/read/scroll</code></li> <li><code>indices:data/write/bulk</code></li> </ul> </li> </ul> <p>About <code>indices:*</code> in Cluster Permissions</p> <p>It is crucial to include <code>indices:*</code> permissions in Cluster Permissions for the proper functioning of the OpenCTI integration. Removing these, even if already present in Index Permissions, may result in startup issues for the OpenCTI Platform.</p>"},{"location":"deployment/rollover/#elasticsearch-configuration","title":"ElasticSearch configuration","text":""},{"location":"deployment/rollover/#indices","title":"Indices","text":"<p>By default, a rollover policy is applied on all indices used by OpenCTI.</p> <ul> <li><code>opencti_deleted_objects</code></li> <li><code>opencti_files</code></li> <li><code>opencti_history</code></li> <li><code>opencti_inferred_entities</code></li> <li><code>opencti_inferred_relationships</code></li> <li><code>opencti_internal_objects</code></li> <li><code>opencti_internal_relationships</code></li> <li><code>opencti_stix_core_relationships</code></li> <li><code>opencti_stix_cyber_observable_relationships</code></li> <li><code>opencti_stix_cyber_observables</code></li> <li><code>opencti_stix_domain_objects</code></li> <li><code>opencti_stix_meta_objects</code></li> <li><code>opencti_stix_meta_relationships</code></li> <li><code>opencti_stix_sighting_relationships</code></li> </ul> <p>For your information, the indices which can grow rapidly are:</p> <ul> <li>Index <code>opencti_stix_meta_relationships</code>: it contains all the nested relationships between objects and labels / marking definitions / external references / authors, etc.</li> <li>Index <code>opencti_history</code>: it contains the history log of all objects in the platform.</li> <li>Index <code>opencti_stix_cyber_observables</code>: it contains all observables stored in the platform.</li> <li>Index <code>opencti_stix_core_relationships</code>: it contains all main STIX relationships stored in the platform.</li> </ul>"},{"location":"deployment/rollover/#default-implemented-lifecycle-policy","title":"Default implemented lifecycle policy","text":"<p>Here is the recommended policy (initialized starting 5.9.X):</p> <ul> <li>Maximum primary shard size: <code>50 GB</code></li> <li>Maximum age: <code>365 days</code></li> <li>Maximum documents: <code>75,000,000</code></li> </ul>"},{"location":"deployment/rollover/#applying-rollover-policies-on-existing-indices","title":"Applying rollover policies on existing indices","text":"<p>Procedure information</p> <p>Please read the following only if your platform has been initialized before 5.9.0, otherwise lifecycle policies has been created (but you can still cutomize them).</p> <p>Unfortunately, to be able to implement rollover policies on ElasticSearch / OpenSearch indices, it will be needed to re-index all the data in new indices using ElasticSearch capabilities.</p>"},{"location":"deployment/rollover/#shutdown","title":"Shutdown","text":"<p>First step is to shutdown your OpenCTI platform.</p>"},{"location":"deployment/rollover/#change-configuration","title":"Change configuration","text":"<p>Then, in the OpenCTI configuration, change the ElasticSearch / OpenSearch default prefix to <code>octi</code> (default is <code>opencti</code>).</p>"},{"location":"deployment/rollover/#create-the-rollover-policy","title":"Create the rollover policy","text":"<p>Create a rollover policy named <code>octi-ilm-policy</code> (in Kibana, <code>Management &gt; Index Lifecycle Policies</code>):</p> <ul> <li>Maximum primary shard size: <code>50 GB</code></li> <li>Maximum age: <code>365 days</code></li> <li>Maximum documents: <code>75,000,000</code></li> </ul> <p></p>"},{"location":"deployment/rollover/#create-index-templates","title":"Create index templates","text":"<p>In Kibana, clone the <code>opencti-index-template</code> to have one index template by OpenCTI index with the appropriate rollover policy, index pattern and rollover alias (in Kibana, <code>Management &gt; Index Management &gt; Index Templates</code>).</p> <p></p> <p>Create the following index templates:</p> <ul> <li><code>octi_deleted_objects</code></li> <li><code>octi_files</code></li> <li><code>octi_history</code></li> <li><code>octi_inferred_entities</code></li> <li><code>octi_inferred_relationships</code></li> <li><code>octi_internal_objects</code></li> <li><code>octi_internal_relationships</code></li> <li><code>octi_stix_core_relationships</code></li> <li><code>octi_stix_cyber_observable_relationships</code></li> <li><code>octi_stix_cyber_observables</code></li> <li><code>octi_stix_domain_objects</code></li> <li><code>octi_stix_meta_objects</code></li> <li><code>octi_stix_meta_relationships</code></li> <li><code>octi_stix_sighting_relationships</code></li> </ul> <p>Here is the overview of all templates (you should have something with <code>octi_</code> instead of <code>opencti_</code>).</p> <p></p>"},{"location":"deployment/rollover/#apply-rollover-policy-on-all-index-templates","title":"Apply rollover policy on all index templates","text":"<p>Then, going back in the index lifecycle policies screen, you can click on the \"+\" button of the <code>octi-ilm-policy</code> to <code>Add the policy to index template</code>, then add the policy to add previously created template with the proper \"Alias for rollover index\".</p> <p></p>"},{"location":"deployment/rollover/#bootstrap-all-new-indices","title":"Bootstrap all new indices","text":"<p>Before we can re-index, we need to create the new indices with aliases.</p> <pre><code>PUT octi_history-000001\n{\n  \"aliases\": {\n    \"octi_history\": {\n      \"is_write_index\": true\n    }\n  }\n}\n</code></pre> <p>Repeat this step for all indices:</p> <ul> <li><code>octi_deleted_objects</code></li> <li><code>octi_files</code></li> <li><code>octi_history</code></li> <li><code>octi_inferred_entities</code></li> <li><code>octi_inferred_relationships</code></li> <li><code>octi_internal_objects</code></li> <li><code>octi_internal_relationships</code></li> <li><code>octi_stix_core_relationships</code></li> <li><code>octi_stix_cyber_observable_relationships</code></li> <li><code>octi_stix_cyber_observables</code></li> <li><code>octi_stix_domain_objects</code></li> <li><code>octi_stix_meta_objects</code></li> <li><code>octi_stix_meta_relationships</code></li> </ul>"},{"location":"deployment/rollover/#re-index-all-indices","title":"Re-index all indices","text":"<p>Using the <code>reindex</code> API, re-index all indices one by one:</p> <pre><code>curl -X POST \"localhost:9200/_reindex?pretty\" -H 'Content-Type: application/json' -d'\n{\n  \"source\": {\n    \"index\": \"opencti_history-000001\"\n  },\n  \"dest\": {\n    \"index\": \"octi_history\"\n  }\n}\n'\n</code></pre> <p>You will see the rollover policy to be applied and the new indices are automatically rolled-over during re-indexation.</p>"},{"location":"deployment/rollover/#delete-all-old-indices","title":"Delete all old indices","text":"<p>Then just delete all indices with the prefix <code>opencti_</code>.</p>"},{"location":"deployment/rollover/#start-your-platform","title":"Start your platform","text":"<p>Start your platform, using the new indices.</p> <p>Rollover documentation</p> <p>To have more details about automatic rollover and lifecycle policies, please read the official ElasticSearch documentation.</p>"},{"location":"deployment/troubleshooting/","title":"Troubleshooting","text":"<p>This page aims to explain the typical errors you can have with your OpenCTI platform.</p>"},{"location":"deployment/troubleshooting/#finding-the-relevant-logs","title":"Finding the relevant logs","text":"<p>It is highly recommended to monitor the error logs of the platforms, workers and connectors. All the components have log outputs in an understandable JSON format. If necessary, it is always possible to increase the log level. In production, it is recommended to have the log level set to <code>error</code>.</p>"},{"location":"deployment/troubleshooting/#platform","title":"Platform","text":"<p>Here are some useful parameters for platform logging:</p> <pre><code>- APP__APP_LOGS__LOGS_LEVEL=[error|warning|info|debug]\n- APP__APP_LOGS__LOGS_CONSOLE=true # Output in the container console\n</code></pre>"},{"location":"deployment/troubleshooting/#connectors","title":"Connectors","text":"<p>All connectors support the same set of parameters to manage the log level and outputs:</p> <pre><code>- OPENCTI_JSON_LOGGING=true # Enable / disable JSON logging\n- CONNECTOR_LOG_LEVEL=info=[error|warning|info|debug]\n</code></pre>"},{"location":"deployment/troubleshooting/#workers","title":"Workers","text":"<p>The workers can have more or less verbose outputs:</p> <pre><code>- OPENCTI_JSON_LOGGING=true # Enable / disable JSON logging\n- WORKER_LOG_LEVEL=[error|warning|info|debug]\n</code></pre>"},{"location":"deployment/troubleshooting/#elasticsearch-opensearch-data","title":"ElasticSearch / OpenSearch data","text":"<p>Kibana / OpenSearch dashboard</p> <p>In case you need to troubleshoot the OpenCTI knowledge data, we recommend to install Kibana or OpenSearch dashboard.</p>"},{"location":"deployment/troubleshooting/#common-errors","title":"Common errors","text":""},{"location":"deployment/troubleshooting/#ingestion-technical-errors","title":"Ingestion technical errors","text":"<p>Missing reference to handle creation</p> <p>After 5 retries, if an element required to create another element is missing, the platform raises an exception. It usually comes from a connector that generates inconsistent STIX 2.1 bundles.</p> <p>Cant upsert entity. Too many entities resolved</p> <p>OpenCTI received an entity which is matching too many other entities in the platform. In this condition we cannot take a decision. We need to dig into the data bundle to identify why it matches too much entities and fix the data in the bundle / or the platform according to what you expect.</p> <p>Execution timeout, too many concurrent call on the same entities</p> <p>The platform supports multi workers and multiple parallel creation but different parameters can lead to some locking timeout in the execution. </p> <ul> <li>Throughput capacity of your ElasticSearch</li> <li>Number of workers started at the same time</li> <li>Dependencies between data</li> <li>Merging capacity of OpenCTI</li> </ul> <p>If you have this kind of error, limit the number of workers deployed. Try to find the right balance of the number of workers, connectors and elasticsearch sizing.</p>"},{"location":"deployment/troubleshooting/#ingestion-functional-errors","title":"Ingestion functional errors","text":"<p>Indicator of type yara is not correctly formatted</p> <p>OpenCTI check the validity of the indicator rule.</p> <p>Observable of type IPv4-Addr is not correctly formatted</p> <p>OpenCTI check the validity of the observable value.</p>"},{"location":"deployment/troubleshooting/#dependencies-errors","title":"Dependencies errors","text":"<p>TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark...</p> <p>Disk full, no space left on the device for ElasticSearch.</p>"},{"location":"deployment/upgrade/","title":"Upgrade","text":"<p>Depending on your installation mode, upgrade path may change.</p> <p>Migrations</p> <p>The platform is taking care of all necessary underlying migrations in the databases if any. You can upgrade OpenCTI from any version to the latest one, including skipping multiple major releases.</p>"},{"location":"deployment/upgrade/#using-docker","title":"Using Docker","text":"<p>Before applying this procedure, please update your <code>docker-compose.yml</code> file with the new version number of container images.</p>"},{"location":"deployment/upgrade/#for-single-node-docker","title":"For single node Docker","text":"<pre><code>$ sudo docker-compose stop\n$ sudo docker-compose pull\n$ sudo docker-compose up -d\n</code></pre>"},{"location":"deployment/upgrade/#for-docker-swarm","title":"For Docker swarm","text":"<p>For each of services, you have to run the following command:</p> <pre><code>$ sudo docker service update --force service_name\n</code></pre>"},{"location":"deployment/upgrade/#manual-installation","title":"Manual installation","text":"<p>When upgrading the platform, you have to replace all files and restart the platform, the database migrations will be done automatically:</p> <pre><code>$ yarn serv\n</code></pre>"},{"location":"development/api-usage/","title":"GraphQL playground","text":"<p>The GraphQL playground is an integrated development environment (IDE) provided by OpenCTI for exploring and testing GraphQL APIs. It offers a user-friendly interface that allows developers to interactively query the GraphQL schema, experiment with different queries, and visualize the responses.</p>"},{"location":"development/api-usage/#key-features","title":"Key features","text":""},{"location":"development/api-usage/#interactive-querying","title":"Interactive querying","text":"<p>The Playground provides a text editor where developers can write GraphQL queries, mutations, and subscriptions. As you type, the Playground offers syntax highlighting, autocompletion, and error checking to aid in query composition.</p> <p></p>"},{"location":"development/api-usage/#documentation","title":"Documentation","text":"<p>Developers can access comprehensive documentation for the GraphQL schema directly within the Playground. This documentation includes descriptions of all available types, fields, and directives, making it easy to understand the data model and construct queries.</p> <p></p>"},{"location":"development/api-usage/#query-history","title":"Query history","text":"<p>The playground keeps track of previously executed queries, allowing developers to revisit and reuse queries from previous sessions. This feature streamlines the development process by eliminating the need to retype complex queries.</p> <p></p>"},{"location":"development/api-usage/#response-visualization","title":"Response visualization","text":"<p>Upon executing a query, the playground displays the response data in a structured and readable format. JSON responses are presented in a collapsible tree view, making it easy to navigate nested data structures and inspect individual fields.</p> <p></p>"},{"location":"development/api-usage/#schema-exploration","title":"Schema exploration","text":"<p>Developers can explore the GraphQL schema using the built-in schema viewer. This feature provides a graphical representation of the schema, showing types, fields, and their relationships. Developers can explore the schema and understand its structure.</p> <p></p>"},{"location":"development/api-usage/#getting-started","title":"Getting started","text":"<p>To access the GraphQL playground, navigate to the GraphQL endpoint of your OpenCTI instance: <code>https://[your-opencti-instance]/graphql</code>. Then, follow these steps to utilize the playground:</p> <ol> <li>Query editor: Write GraphQL queries, mutations, and subscriptions in the text editor. Use syntax highlighting and autocompletion to speed up query composition.</li> <li>Documentation explorer: Access documentation for the GraphQL schema by clicking on the \"Docs\" tab on the right. Browse types, fields, and descriptions to understand the available data and query syntax.</li> <li>Query history: View and execute previously executed queries from the \"History\" tab on the top. Reuse queries and experiment with variations without retyping.</li> <li>Response pane: Visualize query responses in the response pane. Expand and collapse sections to navigate complex data structures and inspect individual fields.</li> <li>Schema viewer: Explore the GraphQL schema interactively using the \"Schema\" tab on the right. Navigate types, fields, and relationships to understand the data model and plan queries.</li> </ol>"},{"location":"development/api-usage/#external-resources","title":"External Resources","text":"<p>For a more in-depth understanding of GraphQL and its usage, consider exploring the following external resources:</p> <ul> <li>GraphQL Official Documentation</li> <li>GraphQL query documentation</li> <li>How to GraphQL</li> </ul>"},{"location":"development/connectors/","title":"Connector development","text":""},{"location":"development/connectors/#introduction","title":"Introduction","text":"<p>A connector in OpenCTI is a service that runs next to the platform and can be implemented in almost any programming language that has STIX2 support. Connectors are used to extend the functionality of OpenCTI and allow operators to shift some of the processing workload to external services. To use the conveniently provided OpenCTI connector SDK you need to use Python3 at the moment.</p> <p>We choose to have a very decentralized approach on connectors, in order to bring a maximum freedom to developers and vendors. So a connector on OpenCTI can be defined by a standalone Python 3 process that pushes an understandable format of data to an ingestion queue of messages.</p> <p>Each connector must implement a long-running process that can be launched just by executing the main Python file. The only mandatory dependency is the <code>OpenCTIConnectorHelper</code> class that enables the connector to send data to OpenCTI.</p>"},{"location":"development/connectors/#getting-started","title":"Getting started","text":"<p>In the beginning first think about your use-case to choose and appropriate connector type - what do want to achieve with your connector? The following table gives you an overview of the current connector types and some typical use-cases:</p> <p>Connector types</p> Type Typical use cases Example connector EXTERNAL_IMPORT Integrate external TI provider, Integrate external TI platform AlienVault INTERNAL_ENRICHMENT Enhance existing data with additional knowledge AbuseIP INTERNAL_IMPORT_FILE (Bulk) import knowledge from files Import document INTERNAL_EXPORT_FILE (Bulk) export knowledge to files STIX 2.1, CSV. STREAM Integrate external TI provider, Integrate external TI platform Elastic Security <p>After you've selected your connector type make yourself familiar with STIX2 and the supported relationships in OpenCTI. Having some knowledge about the internal data models with help you a lot with the implementation of your idea.</p>"},{"location":"development/connectors/#preparation","title":"Preparation","text":""},{"location":"development/connectors/#environment-setup","title":"Environment Setup","text":"<p>To develop and test your connector, you need a running OpenCTI instance with the frontend and the messaging broker accessible. If you don't plan on developing anything for the OpenCTI platform or the frontend, the easiest setup for the connector development is using the docker setup, For more details see here.</p>"},{"location":"development/connectors/#coding-setup","title":"Coding Setup","text":"<p>To give you an easy starting point we prepared an example connector in the public repository you can use as template to bootstrap your development.</p> <p>Some prerequisites we recommend to follow this tutorial:</p> <ul> <li>Code editor with good Python3 support (e.g. Visual Studio Code with the Python extension pack)</li> <li>Python3 + setuptools is installed and configured</li> <li>Command shell (either Linux/Mac terminal or WSL on Windows)</li> </ul> <p>In the terminal check out the connectors repository and copy the template connector to <code>$myconnector</code> (replace it with your name throughout the following text examples).</p> <pre><code>$ pip3 install black flake8 pycti\n# Fork the current repository, then clone your fork\n$ git clone https://github.com/YOUR-USERNAME/connectors.git\n$ cd connectors\n$ git remote add upstream https://github.com/OpenCTI-Platform/connectors.git\n# Create a branch for your feature/fix\n$ git checkout -b [branch-name]\n# Copy the appropriate template directory for the connector type\n$ cp -r templates/$connector_type $connector_type/$myconnector\n$ cd $connector_type/$myconnector\n$ ls -R\nDockerfile              docker-compose.yml      requirements.txt\nREADME.md               entrypoint.sh           src\n\n./src:\nlib     main.py\n\n./src/lib:\n$connector_type.py\n</code></pre>"},{"location":"development/connectors/#changing-the-template","title":"Changing the template","text":"<p>There are a few files in the template we need to change for our connector to be unique. You can check for all places you need to change you connector name with the following command (the output will look similar):</p> <pre><code>$ grep -Ri template .\n\nREADME.md:# OpenCTI Template Connector\nREADME.md:| `connector_type`                     | `CONNECTOR_TYPE`                    | Yes          | Must be `Template_Type` (this is the connector type).                                                                                                      |\nREADME.md:| `connector_name`                     | `CONNECTOR_NAME`                    | Yes          | Option `Template`                                                                                                                                          |\nREADME.md:| `connector_scope`                    | `CONNECTOR_SCOPE`                   | Yes          | Supported scope: Template Scope (MIME Type or Stix Object)                                                                                                 |\nREADME.md:| `template_attribute`                 | `TEMPLATE_ATTRIBUTE`                | Yes          | Additional setting for the connector itself                                                                                                                |\ndocker-compose.yml:  connector-template:\ndocker-compose.yml:    image: opencti/connector-template:4.5.5\ndocker-compose.yml:      - CONNECTOR_TYPE=Template_Type\ndocker-compose.yml:      - CONNECTOR_NAME=Template\ndocker-compose.yml:      - CONNECTOR_SCOPE=Template_Scope # MIME type or Stix Object\nentrypoint.sh:cd /opt/opencti-connector-template\nDockerfile:COPY src /opt/opencti-template\nDockerfile:    cd /opt/opencti-connector-template &amp;&amp; \\\nsrc/main.py:class Template:\nsrc/main.py:            \"TEMPLATE_ATTRIBUTE\", [\"template\", \"attribute\"], config, True\nsrc/main.py:        connectorTemplate = Template()\nsrc/main.py:        connectorTemplate.run()\nsrc/config.yml.sample:  type: 'Template_Type'\nsrc/config.yml.sample:  name: 'Template'\nsrc/config.yml.sample:  scope: 'Template_Scope' # MIME type or SCO\n</code></pre> <p>Required changes:</p> <ul> <li> Change <code>Template</code> or <code>template</code>mentions to your connector name e.g. <code>ImportCsv</code> or <code>importcsv</code></li> <li> Change <code>TEMPLATE</code> mentions to your connector name e.g. <code>IMPORTCSV</code></li> <li> Change <code>Template_Scope</code> mentions to the required scope of your connector. For processing imported files, that can be the Mime type e.g. <code>application/pdf</code> or for enriching existing information in OpenCTI, define the STIX object's name e.g. <code>Report</code>. Multiple scopes can be separated by a simple <code>,</code></li> <li> Change <code>Template_Type</code> to the connector type you wish to develop. The OpenCTI types are defined hereafter:<ul> <li>EXTERNAL_IMPORT</li> <li>INTERNAL_ENRICHMENT</li> <li>INTERNAL_EXPORT_FILE</li> <li>INTERNAL_IMPORT_FILE </li> <li>STREAM</li> </ul> </li> </ul>"},{"location":"development/connectors/#development","title":"Development","text":""},{"location":"development/connectors/#initialize-the-opencti-connector-helper","title":"Initialize the OpenCTI connector helper","text":"<p>After getting the configuration parameters of your connector, you have to initialize the OpenCTI connector helper by using the <code>pycti</code> Python library. This is shown in the following example:</p> <pre><code>class TemplateConnector:\n    def __init__(self):\n                # Instantiate the connector helper from config\n        config_file_path = os.path.dirname(os.path.abspath(__file__)) + \"/config.yml\"\n        config = (\n            yaml.load(open(config_file_path), Loader=yaml.SafeLoader)\n            if os.path.isfile(config_file_path)\n            else {}\n        )\n        self.helper = OpenCTIConnectorHelper(config)\n                self.custom_attribute = get_config_variable(\n            \"TEMPLATE_ATTRIBUTE\", [\"template\", \"attribute\"], config\n        )\n</code></pre> <p>Since there are some basic differences in the tasks of the different connector classes, the structure is also a bit class dependent. While the external-import and the stream connector run independently in a regular interval or constantly, the other 3 connector classes only run when being requested by the OpenCTI platform.</p> <p>The self-triggered connectors run independently, but the OpenCTI need to define a callback function, which can be executed for the connector to start its work. This is done via         <code>self.helper.listen(self._process_message)</code> . In the appended examples, the difference of the setup can be seen.</p> <p>Self-triggered Connectors</p> <ul> <li>external-import</li> <li>stream</li> </ul> <p>OpenCTI triggered</p> <ul> <li>internal-enrichment</li> <li>internal-import</li> <li>internal-export</li> </ul> <pre><code>from pycti import OpenCTIConnectorHelper, get_config_variable\n\nclass TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n        self.template_interval = get_config_variable(\n            \"TEMPLATE_INTERVAL\", [\"template\", \"interval\"], config, True\n        )\n\n    def get_interval(self) -&gt; int:\n        return int(self.template_interval) * 60 * 60 * 24\n\n    def run(self) -&gt; None:\n                # Main procedure\n\nif __name__ == \"__main__\":\n    try:\n        template_connector = TemplateConnector()\n        template_connector.run()\n    except Exception as e:\n        print(e)\n        time.sleep(10)\n        exit(0)\n</code></pre> <pre><code>from pycti import OpenCTIConnectorHelper, get_config_variable\n\nclass TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n\n    def _process_message(self, data: dict) -&gt; str:\n                # Main procedure                \n\n    # Start the main loop\n    def start(self) -&gt; None:\n        self.helper.listen(self._process_message)\n\nif __name__ == \"__main__\":\n    try:\n        template_connector = TemplateConnector()\n        template_connector.start()\n    except Exception as e:\n        print(e)\n        time.sleep(10)\n        exit(0)\n</code></pre>"},{"location":"development/connectors/#write-and-read-operations","title":"Write and Read Operations","text":"<p>When using the <code>OpenCTIConnectorHelper</code> class, there are two way for reading from or writing data to the OpenCTI platform.</p> <ol> <li>via the OpenCTI API interface via <code>self.helper.api</code></li> <li>via the OpenCTI worker via <code>self.send_stix2_bundle</code></li> </ol>"},{"location":"development/connectors/#sending-data-to-the-opencti-platform","title":"Sending data to the OpenCTI platform","text":"<p>The recommended way for creating or updating data in the OpenCTI platform is via the OpenCTI worker. This enables the connector to just send and forget about thousands of entities at once to without having to think about the ingestion order, performance or error handling.</p>  \u26a0\ufe0f **Please DO NOT use the api interface to create new objects in connectors.**   <p>The OpenCTI connector helper method <code>send_stix2_bundle</code> must be used to send data to OpenCTI. The <code>send_stix2_bundle</code> function takes 2 arguments.</p> <ol> <li>A serialized STIX2 bundle as a <code>string</code> (mandatory)</li> <li>A <code>list</code> of entities types that should be ingested (optional)</li> </ol> <p>Here is an example using the STIX2 Python library:</p> <pre><code>from stix2 import Bundle, AttackPattern\n\n[...]\n\nattack_pattern = AttackPattern(name='Evil Pattern')\n\nbundle_objects = []\nbundle_objects.append(attack_pattern)\n\nbundle = Bundle(objects=bundle_objects).serialize()\nbundles_sent = self.opencti_connector_helper.send_stix2_bundle(bundle)\n</code></pre>"},{"location":"development/connectors/#reading-from-the-opencti-platform","title":"Reading from the OpenCTI platform","text":"<p>Read queries to the OpenCTI platform can be achieved using the API and the STIX IDs can be attached to reports to create the relationship between those two entities.</p> <pre><code>entity = self.helper.api.vulnerability.read(\n    filters={\"key\": \"name\", \"values\": [\"T1234\"]}\n)\n</code></pre> <p>If you want to add the found entity via <code>objects_refs</code> to another SDO, simple add a list of <code>stix_ids</code> to the SDO. Here's an example using the entity from the code snippet above:</p> <pre><code>from stix2 import Report\n\n[...]\n\nreport = Report(\n    id=report[\"standard_id\"],\n  object_refs=[entity[\"standard_id\"]],\n)\n</code></pre>"},{"location":"development/connectors/#logging","title":"Logging","text":"<p>When something crashes at a user's, you as a developer want to know as much as possible about this incident to easily improve your code and remove this issue. To do so, it is very helpful if your connector documents what it does. Use <code>info</code> messages for big changes like the beginning or the finishing of an operation, but to facilitate your bug removal attempts, implement <code>debug</code> messages for minor operation changes to document different steps in your code.</p> <p>When encountering a crash, the connector's user can easily restart the troubling connector with the debug logging activated.</p> <ul> <li><code>CONNECTOR_LOG_LEVEL=debug</code></li> </ul> <p>Using those additional log messages, the bug report is more enriched with information about the possible cause of the problem. Here's an example of how the logging should be implemented:</p> <pre><code>        def run(self) -&gt; None:\n                self.helper.log_info('Template connector starts')\n                results = self._ask_for_news()\n                [...]\n\n        def _ask_for_news() -&gt; None:\n                overall = []\n                for i in range(0, 10):\n                        self.log_debug(f\"Asking about news with count '{i}'\")\n                        # Do something\n                        self.log_debug(f\"Resut: '{result}'\")\n                        overall.append(result)\n                return overall\n</code></pre> <p>Please make sure that the debug messages rich of useful information, but that they are not redundant and that the user is not drowned by unnecessary information.</p>"},{"location":"development/connectors/#additional-implementations","title":"Additional implementations","text":"<p>If you are still unsure about how to implement certain things in your connector, we advise you to have a look at the code of other connectors of the same type. Maybe they are already using approach which is suitable for addressing to your problem.</p>"},{"location":"development/connectors/#opencti-triggered-connector-special-cases","title":"OpenCTI triggered Connector - Special cases","text":""},{"location":"development/connectors/#data-layout-of-dictionary-from-callback-function","title":"Data Layout of Dictionary from Callback function","text":"<p>OpenCTI sends the connector a few instructions via the <code>data</code> dictionary in the callback function. Depending on the connector type, the data dictionary content is a bit different. Here are a few examples for each connector type.</p> <p>Internal Import Connector</p> <p>Internal Enrichment Connector</p> <pre><code>{ \n  \"file_id\": \"&lt;fileId&gt;\",\n  \"file_mime\": \"application/pdf\", \n  \"file_fetch\": \"storage/get/&lt;file_id&gt;\", // Path to get the file\n  \"entity_id\": \"report--82843863-6301-59da-b783-fe98249b464e\", // Context of the upload\n}\n</code></pre> <pre><code>{ \n  \"entity_id\": \"&lt;stixCoreObjectId&gt;\" // StixID of the object wanting to be enriched\n}\n</code></pre> <p>Internal Export Connector</p> <pre><code>{ \n  \"export_scope\": \"single\", // 'single' or 'list'\n  \"export_type\": \"simple\", // 'simple' or 'full'\n  \"file_name\": \"&lt;fileName&gt;\", // Export expected file name\n  \"max_marking\": \"&lt;maxMarkingId&gt;\", // Max marking id\n  \"entity_type\": \"AttackPattern\", // Exported entity type\n  // ONLY for single entity export\n  \"entity_id\": \"&lt;entity.id&gt;\", // Exported element\n  // ONLY for list entity export\n  \"list_params\": \"[&lt;parameters&gt;]\" // Parameters for finding entities\n}\n</code></pre>"},{"location":"development/connectors/#self-triggered-connector-special-cases","title":"Self triggered Connector - Special cases","text":""},{"location":"development/connectors/#initiating-a-work-before-pushing-data","title":"Initiating a 'Work' before pushing data","text":"<p>For self-triggered connectors, OpenCTI has to be told about new jobs to process and to import. This is done by registering a so called <code>work</code> before sending the stix bundle and signalling the end of a work. Here an example:</p> <p>By implementing the work registration, they will show up as shown in this screenshot for the MITRE ATT&amp;CK connector:</p> <pre><code>def run() -&gt; None:\n        # Anounce upcoming work\n        timestamp = int(time.time())\n        now = datetime.utcfromtimestamp(timestamp)\n    friendly_name = \"Template run @ \" + now.strftime(\"%Y-%m-%d %H:%M:%S\")\n    work_id = self.helper.api.work.initiate_work(\n                self.helper.connect_id, friendly_name\n        )\n\n        [...]\n        # Send Stix bundle\n        self.helper.send_stix2_bundle(\n                bundle,\n                entities_types=self.helper.connect_scope,\n                update=True,\n                work_id=work_id,\n        )\n        # Finish the work\n        self.helper.log_info(\n            f\"Connector successfully run, storing last_run as {str(timestamp)}\"\n    )              \n        message = \"Last_run stored, next run in: {str(round(self.get_interval() / 60 / 60 / 24, 2))} days\"\n        self.helper.api.work.to_processed(work_id, message)\n</code></pre>"},{"location":"development/connectors/#interval-handling","title":"Interval handling","text":"<p>The connector is also responsible for making sure that it runs in certain intervals. In most cases, the intervals are definable in the connector config and then only need to be set and updated during the runtime.</p> <pre><code>class TemplateConnector:\n    def __init__(self) -&gt; None:\n                # Initialization procedures\n                [...]\n        self.template_interval = get_config_variable(\n            \"TEMPLATE_INTERVAL\", [\"template\", \"interval\"], config, True\n        )\n\n    def get_interval(self) -&gt; int:\n        return int(self.template_interval) * 60 * 60 * 24\n\n        def run(self) -&gt; None:\n        self.helper.log_info(\"Fetching knowledge...\")\n        while True:\n            try:\n                # Get the current timestamp and check\n                timestamp = int(time.time())\n                current_state = self.helper.get_state()\n                if current_state is not None and \"last_run\" in current_state:\n                    last_run = current_state[\"last_run\"]\n                    self.helper.log_info(\n                        \"Connector last run: \"\n                        + datetime.utcfromtimestamp(last_run).strftime(\n                            \"%Y-%m-%d %H:%M:%S\"\n                        )\n                    )\n                else:\n                    last_run = None\n                    self.helper.log_info(\"Connector has never run\")\n                # If the last_run is more than interval-1 day\n                if last_run is None or (\n                    (timestamp - last_run)\n                    &gt; ((int(self.template_interval) - 1) * 60 * 60 * 24)\n                ):\n                    timestamp = int(time.time())\n                    now = datetime.utcfromtimestamp(timestamp)\n                    friendly_name = \"Connector run @ \" + now.strftime(\"%Y-%m-%d %H:%M:%S\")\n\n                                        ###\n                                        # RUN CODE HERE     \n                                        ###\n\n                    # Store the current timestamp as a last run\n                    self.helper.log_info(\n                        \"Connector successfully run, storing last_run as \"\n                        + str(timestamp)\n                    )\n                    self.helper.set_state({\"last_run\": timestamp})\n                    message = (\n                        \"Last_run stored, next run in: \"\n                        + str(round(self.get_interval() / 60 / 60 / 24, 2))\n                        + \" days\"\n                    )\n                    self.helper.api.work.to_processed(work_id, message)\n                    self.helper.log_info(message)\n                    time.sleep(60)\n                else:\n                    new_interval = self.get_interval() - (timestamp - last_run)\n                    self.helper.log_info(\n                        \"Connector will not run, next run in: \"\n                        + str(round(new_interval / 60 / 60 / 24, 2))\n                        + \" days\"\n                    )\n                    time.sleep(60)\n</code></pre>"},{"location":"development/connectors/#running-the-connector","title":"Running the connector","text":"<p>For development purposes, it is easier to simply run the python script locally until everything works as it sould.</p> <pre><code>$ virtualenv env\n$ source ./env/bin/activate\n$ pip3 install -r requirements\n$ cp config.yml.sample config.yml\n# Define the opencti url and token, as well as the connector's id\n$ vim config.yml\n$ python3 main.py\nINFO:root:Listing Threat-Actors with filters null.\nINFO:root:Connector registered with ID: a2de809c-fbb9-491d-90c0-96c7d1766000\nINFO:root:Starting ping alive thread\n...\n</code></pre>"},{"location":"development/connectors/#final-testing","title":"Final Testing","text":"<p>Before submitting a Pull Request, please test your code for different use cases and scenarios. We don't have an automatic testing suite for the connectors yet, thus we highly depend on developers thinking about creative scenarios their code could encounter.</p>"},{"location":"development/connectors/#prepare-for-release","title":"Prepare for release","text":"<p>If you plan to provide your connector to be used by the community (\u2764\ufe0f) your code should pass the following (minimum) criteria.</p> <pre><code># Linting with flake8 contains no errors or warnings\n$ flake8 --ignore=E,W\n# Verify formatting with black\n$ black .\nAll done! \u2728 \ud83c\udf70 \u2728\n1 file left unchanged.\n# Verify import sorting\n$ isort --profile black .\nFixing /path/to/connector/file.py\n# Push you feature/fix on Github\n$ git add [file(s)]\n$ git commit -m \"[connector_name] descriptive message\"\n$ git push origin [branch-name]\n# Open a pull request with the title \"[connector_name] message\"\n</code></pre> <p>If you have any trouble with this just reach out to the OpenCTI core team. We are happy to assist with this.</p>"},{"location":"development/environment_ubuntu/","title":"Prerequisites Ubuntu","text":"<p>Development stack require some base software that need to be installed.</p>"},{"location":"development/environment_ubuntu/#docker-or-podman","title":"Docker or podman","text":"<p>Platform dependencies in development are deployed through container management, so you need to install a container stack.</p> <p>We currently support docker and podman.</p> <pre><code>$ sudo apt-get install docker docker-compose curl\n</code></pre> <pre><code>sudo apt-get -y install podman\n</code></pre> <p>As OpenCTI has a dependency to ElasticSearch, you have to set the vm.max_map_count before running the containers, as mentioned in the ElasticSearch documentation.</p> <pre><code>$ sudo sysctl -w vm.max_map_count=262144\n</code></pre>"},{"location":"development/environment_ubuntu/#nodejs-and-yarn","title":"NodeJS and yarn","text":"<p>The platform is developed on nodejs technology, so you need to install node and the yarn package manager.</p> <pre><code>$ sudo apt-get install nodejs\n$ sudo curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -\n$ sudo echo \"deb https://dl.yarnpkg.com/debian/ stable main\" | sudo tee /etc/apt/sources.list.d/yarn.list\n$ sudo apt-get update &amp;&amp; sudo apt-get install yarn\n</code></pre>"},{"location":"development/environment_ubuntu/#python-runtime","title":"Python runtime","text":"<p>For worker and connectors, a python runtime is needed.</p> <pre><code>$ sudo apt-get install python3 python3-pip\n</code></pre>"},{"location":"development/environment_ubuntu/#git-and-dev-tool","title":"Git and dev tool","text":"<ul> <li>Install Git from apt</li> </ul> <pre><code>$ sudo apt-get install git-all\n</code></pre> <ul> <li>Install your preferred IDE<ul> <li>Intellij community edition - https://www.jetbrains.com/idea/download/</li> <li>VSCode - https://code.visualstudio.com/</li> </ul> </li> </ul>"},{"location":"development/environment_windows/","title":"Prerequisites Windows","text":"<p>Development stack require some base software that need to be installed.</p>"},{"location":"development/environment_windows/#docker-or-podman","title":"Docker or podman","text":"<p>Platform dependencies in development are deployed through container management, so you need to install a container stack.</p> <p>We currently support docker and postman.</p> <p>Docker Desktop from - https://docs.docker.com/desktop/install/windows-install/</p> <ul> <li>Install new version of - https://docs.microsoft.com/windows/wsl/wsl2-kernel. This will require a reboot.</li> <li>Shell out to CMD as Administrator and run the following powershell command: </li> </ul> <p><code>wsl --set-default-version 2</code></p> <ul> <li>Reboot computer and continue to next step       </li> <li>Load Docker Application</li> <li>NOTE DOCKER LICENSE - You are agreeing to the licence for Non-commercial Open Source Project use. OpenCTI is Open Source and the version you would be possibly contributing to enhancing is the unpaid non-commercial/non-enterprise version. If you intention is different - please consult with your organization's legal/licensing department.</li> <li>Leave Docker Desktop running</li> </ul>"},{"location":"development/environment_windows/#nodejs-and-yarn","title":"NodeJS and yarn","text":"<p>The platform is developed on nodejs technology, so you need to install node and the yarn package manager.</p> <ul> <li>Install NodeJS from - https://nodejs.org/download/release/v16.20.0/node-v16.20.0-x64.msi</li> <li>Select the option for installing Chocolatey on the Tools for Native Modules screen<ul> <li>Will do this install for you automatically - https://chocolatey.org/packages/visualstudio2019-workload-vctools</li> <li>Includes Python 3.11.4</li> </ul> </li> <li> <p>Shell out to CMD prompt as Administrator and install/run:</p> <ul> <li><code>pip3 install pywin32</code></li> </ul> </li> <li> <p>Configure Yarn (https://yarnpkg.com/getting-started/install)</p> </li> <li>Open CMD as Administrator and run the following command:<ul> <li><code>corepack enable</code></li> </ul> </li> </ul>"},{"location":"development/environment_windows/#python-runtime","title":"Python runtime","text":"<p>For worker and connectors, a python runtime is needed. Even if you already have a python runtime installed through node installation,  on windows some nodejs package will be recompiled with python and C++ runtime. </p> <p>For this reason Visual Studio Build Tools is required.</p> <ul> <li>Install Visual Studio Build Tools from - https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools</li> <li>Check off Desktop Development with C++</li> <li>Run install</li> </ul>"},{"location":"development/environment_windows/#git-and-dev-tool","title":"Git and dev tool","text":"<ul> <li>Download GIT for Windows (64-bit Setup)- https://git-scm.com/download/win</li> <li> <p>Just use defaults on each screen</p> </li> <li> <p>Install your preferred IDE</p> </li> <li>Intellij community edition - https://www.jetbrains.com/idea/download/</li> <li>VSCode - https://code.visualstudio.com/docs/?dv=win64</li> </ul>"},{"location":"development/platform/","title":"Platform development","text":""},{"location":"development/platform/#introduction","title":"Introduction","text":"<p>This summary should give you a detailed setup description for initiating the OpenCTI setup environment  necessary for developing on the OpenCTI platform, a client library or the connectors.  This page document how to set up an \"All-in-One\" development environment for OpenCTI.  The devenv will contain data of 3 different repositories:</p> <ul> <li>Platform: https://github.com/OpenCTI-Platform/opencti</li> <li>Connectors: https://github.com/OpenCTI-Platform/connectors</li> <li>Client python: https://github.com/OpenCTI-Platform/client-python</li> </ul>"},{"location":"development/platform/#platform","title":"Platform","text":"<p>Contains the platform OpenCTI project code base:</p> <ul> <li>docker-compose (docker or podman) <code>~/opencti/opencti-platform/opencti-dev</code></li> <li>Web frontend (nodejs / react) <code>~/opencti/opencti-platform/opencti-graphql</code></li> <li>Backend (nodejs) <code>~/opencti/opencti-platform/opencti-frontend</code></li> <li>Worker (nodejs / python) <code>~/opencti/opencti-worker</code></li> </ul>"},{"location":"development/platform/#connectors","title":"Connectors","text":"<p>Contains a lot of developed connectors, as a source of inspiration for your new connector.</p>"},{"location":"development/platform/#client-python","title":"Client python","text":"<p>Contains the source code of the python library used in worker or connectors.</p>"},{"location":"development/platform/#prerequisites","title":"Prerequisites","text":"<p>Some tools are needed before starting to develop. Please check Ubuntu prerequisites or Windows prerequisites</p>"},{"location":"development/platform/#clone-the-projects","title":"Clone the projects","text":"<p>Fork and clone the git repositories</p> <ul> <li>https://github.com/OpenCTI-Platform/opencti/ - frontend / backend</li> <li>https://github.com/OpenCTI-Platform/connectors - connectors</li> <li>https://github.com/OpenCTI-Platform/docker - docker stack</li> <li>https://github.com/OpenCTI-Platform/client-python/ - python client</li> </ul>"},{"location":"development/platform/#dependencies-containers","title":"Dependencies containers","text":"<p>In development dependencies are deployed trough containers. A development compose file is available in <code>~/opencti/opencti-platform/opencti-dev</code></p> <pre><code>cd ~/docker\n#Start the stack in background\ndocker-compose -f ./docker-compose-dev.yml up -d\n</code></pre> <p>You have now all the dependencies of OpenCTI running and waiting for product to run.</p>"},{"location":"development/platform/#backend-api","title":"Backend / API","text":""},{"location":"development/platform/#python-virtual-env","title":"Python virtual env","text":"<p>The GraphQL API is developed in JS and with some python code.  As it's an \"all-in-one\" installation, the python environment will be installed in a virtual environment.</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\npython3 -m venv .venv --prompt \"graphql\"\nsource .venv/bin/activate\npip install --upgrade pip wheel setuptools\nyarn install\nyarn install:python \ndeactivate\n</code></pre>"},{"location":"development/platform/#development-configuration","title":"Development configuration","text":"<p>The API can be specifically configured with files depending on the starting profile. By default, the default.json file is used and will be correctly configured for local usage except for admin password</p> <p>So you need to create a development profile file. You can duplicate the default file and adapt if for you need. <pre><code>cd ~/opencti/opencti-platform/opencti-graphql/config\ncp default.json development.json\n</code></pre></p> <p>At minimum adapt the admin part for the password and token. <pre><code>    \"admin\": {\n      \"email\": \"admin@opencti.io\",\n      \"password\": \"MyNewPassord\",\n      \"token\": \"UUID generated with https://www.uuidgenerator.net\"\n    }\n</code></pre></p>"},{"location":"development/platform/#install-start","title":"Install / start","text":"<p>Before starting the backend you need to install the nodejs modules</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\nyarn install\n</code></pre> <p>Then you can simply start the backend API with the yarn start command</p> <pre><code>cd ~/opencti/opencti-platform/opencti-graphql\nyarn start\n</code></pre> <p>The platform will start logging some interesting information</p> <pre><code>{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] Starting platform\",\"timestamp\":\"2023-07-02T16:37:10.984Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] Checking dependencies statuses\",\"timestamp\":\"2023-07-02T16:37:10.987Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[SEARCH] Elasticsearch (8.5.2) client selected / runtime sorting enabled\",\"timestamp\":\"2023-07-02T16:37:11.014Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[CHECK] Search engine is alive\",\"timestamp\":\"2023-07-02T16:37:11.015Z\",\"version\":\"5.8.7\"}\n...\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[INIT] Platform initialization done\",\"timestamp\":\"2023-07-02T16:37:11.622Z\",\"version\":\"5.8.7\"}\n{\"category\":\"APP\",\"level\":\"info\",\"message\":\"[OPENCTI] API ready on port 4000\",\"timestamp\":\"2023-07-02T16:37:12.382Z\",\"version\":\"5.8.7\"}\n</code></pre> <p>If you want to start on another profile you can use the -e parameter. For example here to use the profile.json configuration file.</p> <pre><code>yarn start -e profile\n</code></pre>"},{"location":"development/platform/#code-check","title":"Code check","text":"<p>Before pushing your code you need to validate the syntax and ensure the testing will be validated.</p>"},{"location":"development/platform/#for-validation","title":"For validation","text":"<p><code>yarn lint</code></p> <p><code>yarn check-ts</code></p>"},{"location":"development/platform/#for-testing","title":"For testing","text":"<p>For starting the test you will need to create a test.json configuration file. You can use the same dependencies by only adapting all prefix for all dependencies.</p> <p>Tests are using dedicated indices in the Elastic database (prefixed with <code>test-*</code> or the prefix that you have set up in test.json).</p> <p>The following command will run the complete test suite using vitest, which might take more than 30 minutes. It starts by cleaning up the test database and seeding a minimal dataset. The file <code>vitest.config.test.ts</code> can be edited to run only a specific file pattern.</p> <p><code>yarn test:dev</code></p> <p>We also provide utility scripts to ease the development of new tests, especially integration tests that rely on the sample data  loaded after executing <code>00-inject/loader-test.ts</code>.</p> <p>To solely initialize the test database with this sample dataset run:</p> <p><code>yarn test:dev:init</code></p> <p>And then, execute the following command to run the pattern specified in the file <code>vitest.config.test.ts</code>, or add a file name to the command line to run only this test file.</p> <p><code>yarn test:dev:resume</code></p> <p>This last command will NOT cleanup &amp; initialize the test database and thus will be quicker to execute. </p>"},{"location":"development/platform/#frontend","title":"Frontend","text":""},{"location":"development/platform/#install-start_1","title":"Install / start","text":"<p>Before starting the backend you need to install the nodejs modules</p> <pre><code>cd ~/opencti/opencti-platform/opencti-front\nyarn install\n</code></pre> <p>Then you can simply start the frontend with the yarn start command</p> <pre><code>cd ~/opencti/opencti-platform/opencti-front\nyarn start\n</code></pre> <p>The frontend will start with some interesting information</p> <pre><code>[INFO] [default] compiling...\n[INFO] [default] compiled documents: 1592 reader, 1072 normalization, 1596 operation text\n[INFO] Compilation completed.\n[INFO] Done.\n[HPM] Proxy created: /stream  -&gt; http://localhost:4000\n[HPM] Proxy created: /storage  -&gt; http://localhost:4000\n[HPM] Proxy created: /taxii2  -&gt; http://localhost:4000\n[HPM] Proxy created: /feeds  -&gt; http://localhost:4000\n[HPM] Proxy created: /graphql  -&gt; http://localhost:4000\n[HPM] Proxy created: /auth/**  -&gt; http://localhost:4000\n[HPM] Proxy created: /static/flags/**  -&gt; http://localhost:4000\n</code></pre> <p>The web UI should be accessible on http://127.0.0.1:3000</p>"},{"location":"development/platform/#code-check_1","title":"Code check","text":"<p>Before pushing your code you need to validate the syntax and ensure the testing will be validated.</p>"},{"location":"development/platform/#for-validation_1","title":"For validation","text":"<p><code>yarn lint</code></p> <p><code>yarn check-ts</code></p>"},{"location":"development/platform/#for-testing_1","title":"For testing","text":"<p><code>yarn test</code></p>"},{"location":"development/platform/#worker","title":"Worker","text":"<p>Running a worker is required when you want to develop on the ingestion or import/export connectors.</p>"},{"location":"development/platform/#python-virtual-env_1","title":"Python virtual env","text":"<pre><code>cd ~/opencti/opencti-worker/src\npython3 -m venv .venv --prompt \"worker\"\nsource .venv/bin/activate\npip3 install --upgrade pip wheel setuptools\npip3 install -r requirements.txt\ndeactivate\n</code></pre>"},{"location":"development/platform/#install-start_2","title":"Install / start","text":"<pre><code>cd ~/opencti/opencti-worker/src\nsource .venv/bin/activate\npython worker.py\n</code></pre>"},{"location":"development/platform/#connectors_1","title":"Connectors","text":"<p>For connectors development, please take a look to Connectors development dedicated page.</p>"},{"location":"development/platform/#production-build","title":"Production build","text":"<p>Based on development source you can build the package for production. This package will be minified and optimized with esbuild.</p> <pre><code>$ cd opencti-frontend\n$ yarn build\n$ cd ../opencti-graphql\n$ yarn build\n</code></pre> <p>After the build you can start the production build with yarn serv. This build will use the production.json configuration file</p> <pre><code>$ cd ../opencti-graphql\n$ yarn serv\n</code></pre>"},{"location":"development/platform/#continous-integration-and-features-cross-repository","title":"Continous Integration and features cross repository","text":"<p>When a feature requires changes in two or more repository in opencti, connectors and client-python; then some specific convention must be use to have the continuous integration build them all together.</p>"},{"location":"development/platform/#naming-convention-of-branch","title":"Naming convention of branch","text":"<p>The Pull Request on opencti repository should be (issue or bug)/number + optional, example: <code>issue/7062-contributing</code></p> <p>The pull request on connector or client-python should refer to opencti one by starting with \"opencti/\" and then the same name. Example: <code>opencti/issue/7062-contributing</code></p> <p>Note that if there are several matches, the first one is taken. So for example having <code>issue/7062-contributing</code> and <code>issue/7062</code> that are both marked as \"multi-repository\" is not a good idea.</p>"},{"location":"development/platform/#labels","title":"Labels","text":"<p>All Pull Requests involved must have the label <code>multi-repository</code> added in GitHub.</p>"},{"location":"development/python/","title":"Python library","text":"<p>The PyCTI library is the official Python client for OpenCTI. It is made to help developers interact with the openCTI plaform.</p>"},{"location":"development/python/#installation","title":"Installation","text":"<p>To install the latest Python client library, please use <code>pip</code>:</p> <pre><code>$ pip3 install pycti\n</code></pre>"},{"location":"development/python/#using-the-helper-functions","title":"Using the helper functions","text":"<p>The main class <code>OpenCTIApiClient</code> contains all what you need to interact with the platform, you just have to initialize it.</p> <p>The following example shows how you create an indicator in OpenCTI using the python library with TLP marking and OpenCTI compatible date format.</p> <pre><code>from dateutil.parser import parse\nfrom pycti import OpenCTIApiClient\nfrom stix2 import TLP_GREEN\n\n# OpenCTI API client initialization\nopencti_api_client = OpenCTIApiClient(\"https://myopencti.server\", \"mysupersecrettoken\")\n\n# Define an OpenCTI compatible date\ndate = parse(\"2019-12-01\").strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n\n# Get the OpenCTI marking for stix2 TLP_GREEN\nTLP_GREEN_CTI = opencti_api_client.marking_definition.read(id=TLP_GREEN[\"id\"])\n\n# Use the client to create an indicator in OpenCTI\nindicator = opencti_api_client.indicator.create(\n    name=\"C2 server of the new campaign\",\n    description=\"This is the C2 server of the campaign\",\n    pattern_type=\"stix\",\n    pattern=\"[domain-name:value = 'www.5z8.info']\",\n    x_opencti_main_observable_type=\"IPv4-Addr\",\n    valid_from=date,\n    update=True,\n    markingDefinitions=[TLP_GREEN_CTI[\"id\"]],\n)\n</code></pre>"},{"location":"development/python/#examples","title":"Examples","text":"<p>A suite of illustrative examples is available in the PyCTI GitHub repository to aid in better understanding.</p>"},{"location":"reference/api/","title":"GraphQL API","text":"<p>OpenCTI provides a comprehensive API based on GraphQL, allowing users to perform various actions programmatically. The API enables users to interact with OpenCTI's functionality and data, offering a powerful tool for automation, integration, and customization. All actions that can be performed through the platform's graphical interface are also achievable via the API.</p>"},{"location":"reference/api/#authentication","title":"Authentication","text":"<p>Access to the OpenCTI API requires authentication using standard authentication mechanisms. Access rights to data via the API will be determined by the access privileges of the user associated with the API key. For authentication, users need to include the following headers in their API requests:</p> <pre><code>Content-Type: application/json\nAuthorization: Bearer [API key]\n</code></pre>"},{"location":"reference/api/#documentation","title":"Documentation","text":"<p>The OpenCTI API consists of various endpoints corresponding to different functionalities and operations within the platform. These endpoints allow users to perform actions such as querying data, creating or updating entities, and more. Users can refer to the Understand GraphQL section to understand how it works.</p> <p>Documentation for the OpenCTI API, including schema definitions, the list of filters available and queryable fields, is available through the OpenCTI platform. It can be found on the GraphQL playground. However, query examples and mutation examples are not yet available. In the meantime, users can explore the available endpoints and their functionality by inspecting network traffic in the browser's developer tools or by examining the source code of the Python client.</p> <p></p> <p></p>"},{"location":"reference/api/#understand-graphql","title":"Understand GraphQL","text":"<p>GraphQL is a powerful query language for APIs that enables clients to request exactly the data they need. Unlike traditional REST APIs, which expose fixed endpoints and return predefined data structures, GraphQL APIs allow clients to specify the shape and structure of the data they require.</p>"},{"location":"reference/api/#core-concepts","title":"Core concepts","text":""},{"location":"reference/api/#schema-definition-language-sdl","title":"Schema Definition Language (SDL)","text":"<p>GraphQL APIs are defined by a schema, which describes the types of data that can be queried and the relationships between them. The schema is written using the Schema Definition Language (SDL), which defines types, fields, and their relationships.</p>"},{"location":"reference/api/#query-language","title":"Query language","text":"<p>GraphQL uses a query language to request data from the server. Clients can specify exactly which fields they need and how they are related, enabling precise data retrieval without over-fetching or under-fetching.</p> <p>Example:</p> <pre><code>query IntrusionSets {\n    intrusionSets (\n        filters:\n        {\n            mode: and,\n            filters: [\n                {\n                    key: \"name\",\n                    values: [\"Ajax Security Team\"],\n                    operator: eq,\n                    mode: or,\n                }\n            ],\n            filterGroups: [],\n        }\n    )\n    {\n        edges{\n            node{\n                id\n                name\n                description\n                externalReferences{\n                    edges{\n                        node{\n                            url\n                            source_name\n                        }\n                    }\n                }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"reference/api/#resolvers","title":"Resolvers","text":"<p>Resolvers are functions responsible for fetching the requested data. Each field in the GraphQL schema corresponds to a resolver function, which determines how to retrieve the data from the underlying data sources.</p>"},{"location":"reference/api/#how-it-works","title":"How it Works","text":"<ol> <li>Schema definition: The API provider defines a GraphQL schema using SDL, specifying the types and fields available for querying.</li> <li>Query execution: Clients send GraphQL queries to the server, specifying the data they need. The server processes the query, resolves each field, and constructs a response object with the requested data.</li> <li>Validation and execution: The server validates the query against the schema to ensure it is syntactically and semantically correct. If validation passes, the server executes the query, invoking the appropriate resolver functions to fetch the requested data.</li> <li>Data retrieval: Resolvers fetch data from the relevant data sources, such as databases, APIs, or other services. They transform the raw data into the shape specified in the query and return it to the client.</li> <li>Response formation: Once all resolvers have completed, the server assembles the response object containing the requested data and sends it back to the client.</li> </ol>"},{"location":"reference/api/#external-resources","title":"External Resources","text":"<p>For a more in-depth understanding of GraphQL and its usage, consider exploring the following external resources:</p> <ul> <li>GraphQL Official Documentation</li> <li>GraphQL query documentation</li> <li>How to GraphQL</li> </ul>"},{"location":"reference/data-intelligence/","title":"Data intelligence","text":"<p>As a cyber threat intelligence platform, OpenCTI offers functionalities that enable users to move quickly from raw data to operational intelligence by building up high-quality, structured information.</p> <p>To do so, the platform provides a number of essential capabilities, such as automated data deduplication, merging of similar entities while preserving relationship integrity, the ability to modulate the confidence levels on your intelligence, and the presence of inference rules to automate the creation of logical relationships among your data.</p> <p>The purpose of this page is to list the features of the platform that contribute to the intelligibility and quality of intelligence.</p>"},{"location":"reference/data-intelligence/#deduplication","title":"Deduplication","text":"<p>The first essential data intelligence mechanism in OpenCTI is the deduplication of information and relations.</p> <p>This advanced functionality not only enables you to check whether a piece of data, information or a relationship is not a duplicate of an existing element, but will also, under certain conditions, enrich the element already present.</p> <p>If the new duplicated entity has new content, the pre-existing entity can be enriched with the new information from the duplicate.</p> <p>It works as follows (see details in the dedicated page):</p> <ul> <li>For entities: based on the entity's properties based on a specific ID generated by the \"ID Contributing Properties\" platform (properties listed on the dedicated page).</li> <li>For relationships: based on type, source, target, start time, and stop time.</li> <li>For observables: a specific ID is also generated by the platform, this time based on the specifications of the STIX model.</li> </ul> <p>The ability to update and enrich is determined by the confidence level and quality level of the entities and relationships (see diagram on page deduplication).</p>"},{"location":"reference/data-intelligence/#merging","title":"Merging","text":"<p>OpenCTI's merging function is one of the platform's crucial data intelligence elements.</p> <p>From the Data &gt; Entities tab, this feature lets you merge up to 4 entities of the same type. A parent entity is selected and assigned up to three child entities.</p> <p>The benefit of this feature is to centralize a number of similar elements from different sources without losing data or degrading the quality of the information. During merging, the platform will create relationships to anchor all the data to the consolidated entity.</p> <p>This enrichment function consolidates the data and avoids duplication, but above all initiates a structured intelligence process while preserving the integrity of pre-existing relationships as presented here.</p>"},{"location":"reference/data-intelligence/#confidence-level-and-data-segregation","title":"Confidence level and data segregation","text":"<p>Another key element of OpenCTI's data intelligence is its ability to apply confidence levels and to segregate the data present in the platform.</p> <p>The confidence level is directly linked to users and Role Based Access Control. It is applied to a user directly or indirectly via the confidence level of the group to which the user belongs. This element is fundamental as it defines the levels of data manipulation to which the user (real or connector) is entitled.</p> <p>The correct application of confidence levels is all the more important as it will determine the confidence level of the data manipulated by a user. It is therefore a decisive mechanism, since it underpins the confidence you have in the content of your instance.</p> <p>While it is important to apply a level of trust to your users or groups, it is also important to define a way of categorizing and protecting your data.</p> <p>Data segregation makes it possible to apply marking definitions and therefore establish a standardized framework for classifying data.</p> <p>These marking definitions, like the classic Traffic Light Protocols (TLP) implemented by default in the platform, will determine whether a user can access a specific data set. The marking will be applied at the group level to which the user belongs, which will determine the data to which the user has access and therefore the data that the user can potentially handle.</p>"},{"location":"reference/data-intelligence/#inference-rules","title":"Inference rules","text":"<p>In OpenCTI, data intelligence is not just about the ability to segregate, qualify or enrich data. OpenCTI's inference rules enable you to mobilize the data on your platform effectively and operationally.</p> <p>These predefined rules enable the user to speed up cyber threat management. For example, inferences can be used to automatically identify incidents based on a sighting, to create sightings on observables based on new observed data, to propagate relationships based on an observable, etc.</p> <p>In all, the platform includes some twenty high-performance inference rules that considerably speed up the analysis and response to threats (see the full list here).</p> <p>These rules are based on a logical interpretation of the data, resulting in a pre-analysis of the information by creating relationships that will enrich the intelligence in the platform. There are three main benefits: efficiency, completeness and accuracy. These user benefits can be found here.</p> <p>Note: If these rules are present in the platform, they are not activated by default.</p> <p>Once activated, they scan all the data in your platform in the background to identify all the existing relationships that meet the conditions of the rules. Then, the rules operate continuously to create relationships. If you deactivate a rule, all the objects and relationships it has created will be deleted.</p> <p>These actions can only be carried out by an administrator of the instance.</p>"},{"location":"reference/data-model/","title":"Data model","text":"<p>Under construction</p> <p>This page will be automatically generated to reference the platform's data model. We are doing our best to implement this automatic generation as quickly as possible.</p>"},{"location":"reference/filters-migration/","title":"Filters format migration for OpenCTI 5.12","text":"<p>The version 5.12 of OpenCTI introduces breaking changes to the filters format 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.</p>"},{"location":"reference/filters-migration/#why-this-migration","title":"Why this migration?","text":"<p>Before OpenCTI 5.12, it was not possible to construct complex filters combinations: we couldn't embed filters within filters, used different boolean modes (and/or), filter on all available attributes or relations for a given entity type, or even test for empty fields of any sort.</p> <p>Legacy of years of development, the former format and filtering mechanics were not adapted for such task, and a profound refactoring was necessary to make it happen.</p> <p>Here are the main pain points we identified beforehand:</p> <ul> <li>The filters frontend and backend formats were very different, requiring careful conversions.</li> <li>The filter were static lists of keys, depending on each given entity type and maintained by hands.</li> <li>The operator (<code>eq</code>, <code>not_eq</code>, etc.) was inside the key (e.g. <code>entity_type_not_eq</code>), limiting operator combination and requiring error-prone parsing.</li> <li>The frontend format imposed a unique form of combination (<code>and</code> between filters, <code>or</code> between values inside each filter, and nothing else possible).</li> <li>The flat list structure made impossible filter imbrication by nature.</li> <li>Filters and query options were mixed in GQL queries for the same purpose (for instance, option <code>types</code> analog to a filter on key <code>entity_type</code>).</li> </ul> <pre><code>// filter formats in OpenCTI &lt; 5.12\n\ntype Filter = {\n    key: string, // a key in the list of the available filter keys for given the entity type\n    values: string[],\n    operator: string,\n    filterMode: 'and' | 'or',\n}\n\n// \"give me Reports labelled with labelX or labelY\"\nconst filters = [\n  { \n    \"key\": \"entity_type\",\n    \"values\": [\"Report\"],\n    \"operator\": \"eq\",\n    \"filterMode\": \"or\"\n  },\n  { \n    \"key\": \"labelledBy\",\n    \"values\": [\"&lt;id-for-labelX&gt;\", \"&lt;id-for-labelY&gt;\"],\n    \"operator\": \"eq\",\n    \"filterMode\": \"or\"\n  },\n]\n</code></pre> <p>The new format brings a lot of short-term benefits and is compatible with our long-term vision of the filtering capabilities in OpenCTI. We chose a simple recursive structure that allow complex combination of any sort with respect to basic boolean logic.</p> <p>The list of operator is fixed and can be extended during future developments.</p> <pre><code>// filter formats in OpenCTI &gt;= 5.12\n\ntype FilterGroup = {\n  mode: 'and' | 'or'\n  filters: Filter[]\n  filterGroups: FilterGroup[] // recursive definition\n}\n\ntype Filter  = {\n  key: string[]\n  values: string[]\n  operator: 'eq' | 'not_eq' | 'gt' // ... and more\n  mode: 'and' | 'or',\n}\n\n// \"give me Reports and RFIs, not marked TLP:RED with labelX or no label\"\nconst filters = {\n  mode: 'and',\n  filters: [\n    { key: 'entity_type', values: ['Report', 'Case-Rfi'], operator: 'eq', mode: 'or', },\n    { key: 'objectMarking', values: ['&lt;id-for-TLP:RED&gt;'], operator: 'not_eq', mode: 'or', },\n  ],\n  filterGroups: [{\n    mode: 'or',\n    filters: [\n      { key: 'objectLabel', values: [\"&lt;id-for-labelX&gt;\"], operator: 'eq', mode: 'or', },\n      { key: 'objectLabel', values: [], operator: 'nil', mode: 'or', },\n    ],\n    filterGroups: [],\n  }],\n};\n</code></pre> <p>Because changing filters format impacts almost everything in the platform, we decided to do a complete refactoring once and for all. We want this migration process to be clear and easy.</p>"},{"location":"reference/filters-migration/#what-has-been-changed","title":"What has been changed","text":"<p>The new filter implementation bring major changes in the way filters are processed and executed.</p> <ul> <li> <p>We change the filters formats (see <code>FilterGroup</code> type above):</p> <ul> <li>In the frontend, an operator and a mode are stored for each key.</li> <li>The new format enables filters imbrication thanks to the new attribute 'filterGroups'.</li> <li>The keys are of type string (no more static list of enums).</li> <li>The 'values' attribute can no longer contain null values (use the <code>nil</code> operator instead).</li> </ul> </li> <li> <p>We also renamed some filter keys, to be consistent with the entities schema definitions.</p> </li> <li>We implemented the handling of the different operators and modes in the backend.</li> <li>We introduced new void operators (<code>nil</code> / <code>not_nil</code>) to test the presence or absence of value in any field.</li> </ul>"},{"location":"reference/filters-migration/#how-to-migrate-your-own-filters","title":"How to migrate your own filters","text":"<p>We wrote a migration script to convert all stored filters created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform.</p> <p>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 &gt;= 5.12.</p>"},{"location":"reference/filters-migration/#filter-conversion","title":"Filter conversion","text":"<p>To convert filters prior to version 5.12 in the new format:</p> <ol> <li>update the <code>key</code> field if it has been changed in 5.12 (see the conversion table below),</li> <li>rename the field <code>filterMode</code> in <code>mode</code></li> <li>if <code>values</code> contains <code>null</code>, see below for conversion.</li> </ol> <p>Now you can build your new <code>FilterGroup</code> object with:</p> <ul> <li><code>mode: 'and'</code></li> <li><code>filters</code> = array of converted filters (following previous steps),</li> <li><code>filterGroups: []</code></li> </ul> <pre><code>const oldFilter = {\n    key: 'old_key',\n    values: ['value1', 'value2'],\n    operator: 'XX',\n    filterMode: 'XX',\n}\n\nconst convertedFilter = {\n    key: 'converted_key_if_necessary',\n    values: ['value1', 'value2'],\n    operator: 'XX',\n    mode: 'XX',\n}\n\nconst newFilters = {\n    mode: 'and',\n    filters: [convertedFilter1, convertedFilter2...], // array with all converted filters\n    filterGroups: [],\n}\n</code></pre> <p>If <code>values</code> contains a <code>null</code> value, you need to convert the filter by using the new <code>nil</code> / <code>not_nil</code> operators. Here's the procedure:</p> <ol> <li> <p>Extract one filter dedicated to <code>null</code></p> <ul> <li>if operator was <code>'eq'</code>, switch to <code>operator: 'nil'</code> / if operator was <code>not_eq</code>, switch to <code>operator = 'not_nil'</code></li> <li><code>values = []</code></li> </ul> </li> <li> <p>Extract another filter for all the other values.</p> </li> </ol> <pre><code>// \"Must have a label that is not Label1 or Label2\"\nconst oldFilter = {\n    key: 'labelledBy',\n    values: [null, 'id-for-Label1', 'id-for-Label2'],\n    operator: 'not_eq',\n    filterMode: 'and',\n}\n\nconst newFilters = {\n    mode: 'and',\n    filters: [\n      {\n        key: 'objectLabel',\n        values: ['id-label-1', 'id-for-Label2'],\n        operator: 'not_eq',\n        mode: 'and',\n      },\n      {\n        key: 'objectLabel',\n        values: [],\n        operator: 'not_nil',\n        mode: 'and',\n      },\n    ],\n    filterGroups: [],\n}\n</code></pre> <p>Switch to nested filter to preserve logic</p> <p>To preserve the logic of your old filter you might need to compose nested filter groups. This could happen for instance when using <code>eq</code> operator with <code>null</code> values for one filter, combined in <code>and</code> mode with other filters.</p> <p></p>"},{"location":"reference/filters-migration/#filter-keys-conversion-table","title":"Filter keys conversion table","text":"<p>Make sure you address all the filter keys that require conversion, following the map below:</p> <pre><code>// array of [oldKey, newKey] for the renamed keys\nconst keyConversion = [\n    ['labelledBy', 'objectLabel'],\n    ['markedBy', 'objectMarking'],\n    ['objectContains', 'objects'],\n    ['killChainPhase', 'killChainPhases'],\n    ['assigneeTo', 'objectAssignee'],\n    ['participant', 'objectParticipant'],\n    ['creator', 'creator_id'],\n    ['hasExternalReference', 'externalReferences'],\n    ['hashes_MD5', 'hashes.MD5'],\n    ['hashes_SHA1', 'hashes.SHA-1'],\n    ['hashes_SHA256', 'hashes.SHA-256'],\n    ['hashes_SHA512', 'hashes.SHA-512']\n]\n</code></pre>"},{"location":"reference/filters-migration/#examples","title":"Examples","text":""},{"location":"reference/filters-migration/#simple-example","title":"Simple example","text":"<p>Let's start with a simple case:</p> <p>All Reports with label \"label1\" or \"label2\"</p> <p><code>(entity_type = Report) AND (label = label1 OR label2)</code></p> <pre><code>const oldBackendFilter = [\n  {\n    key: 'entity_type',\n    values: ['Report'],\n    operator: 'eq',\n    filterMode: 'or',\n  },\n  {\n   key: 'labelledBy',\n    values: [label1_id, label2_id],\n    operator: 'eq',\n    filterMode: 'or',\n  },\n];\n\nconst newFilters = {\n  mode: 'and',\n  filters: [\n    {\n      key: 'entity_type',\n      values: ['Report'],\n      operator: 'eq',\n      mode: 'or',\n    },\n    {\n      key: 'objectLabel',\n      values: [label1_id, label2_id],\n      operator: 'eq',\n      mode: 'or',\n    }\n  ],\n  filterGroups: [],\n};\n</code></pre>"},{"location":"reference/filters-migration/#complex-example","title":"Complex example","text":"<p>Now let's see a more complex case involving filter group nesting:</p> <p>\"All Reports that have either the label \"label1\" or \"label2\", or no label at all\"</p> <p><code>(entity_type = Report) AND (label = \"No label\" OR label1 OR label2)</code></p> <pre><code>const oldBackendFilter = [\n    {\n      key: 'labelledBy',\n      values: [label1_id, label2_id, null],\n      operator: 'eq',\n      filterMode: 'or',\n    },\n    {\n      key: 'entity_type',\n      values: ['Report'],\n      operator: 'eq',\n      filterMode: 'or',\n    },\n];\n\nconst newFilters = {\n    mode: 'and',\n    filters: [\n      {\n        key: 'entity_type',\n        values: ['Report'],\n        operator: 'eq',\n        mode: 'or',\n      },\n    ],\n    // the combination mode/operator in this case requires nested filter groups\n    filterGroups: [\n      {\n        mode: 'or',\n        filters: [\n          {\n            key: 'objectLabel',\n            values: [label1_id, label2_id],\n            operator: 'eq',\n            mode: 'or',\n          },\n          {\n            key: 'objectLabel',\n            operator: 'nil',\n            values: [], // empty, does not matter\n            mode: 'or', // and/or, does not matter \n          },\n        ],\n        filterGroups: [],\n      }\n    ],\n};\n</code></pre>"},{"location":"reference/filters-migration/#residual-dynamic-filters","title":"Residual dynamic filters","text":"<p>Dynamic filters are not stored in the database, they enable to filter view in the UI, e.g. filters in entities list, investigations, knowledge graphs. They are saved as URL parameters, and can be saved in local storage.</p> <p>These filters are not migrated automatically and are lost when moving to 5.12. This concerns the filters saved for each view, that are restored when coming back to the same view. You will need to reconstruct the filters by hand in the UI; these new filters will be properly saved and restored afterward.</p> <p>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.</p> <p></p>"},{"location":"reference/filters/","title":"Filter knowledge","text":"<p>In OpenCTI, you can filter data to target or view entities that have particular attributes.</p>"},{"location":"reference/filters/#filters-usages","title":"Filters usages","text":"<p>There are two types of filters that are used in many locations in the platform:</p> <ul> <li>in entities lists: to display only the entities matching the filters. If an export or a background task is generated, only the filtered data will be taken into account,</li> <li>in investigations and knowledge graphs: to display only the entities matching the filters,</li> <li>in dashboards: to create widget with only the entities matching the filters,</li> <li>in feeds, TAXII collections, triggers, streams, playbooks, background tasks: to process only the data or events matching the filters.</li> </ul>"},{"location":"reference/filters/#dynamic-filters","title":"Dynamic filters","text":"<p>Dynamic filters are not stored in the database, they enable to filter view in the UI, e.g. filters in entities list, investigations, knowledge graphs.</p> <p>However, they are still persistent in the platform frontend side. The filters used in a view are saved as URL parameters, so you can save and share links of these filtered views.</p> <p>Also, your web browser saves in local storage the filters that you are setting in various places of the platform, allowing to retrieve them when you come back to the same view. You can then keep working from where you left of.</p> <p></p> <p></p>"},{"location":"reference/filters/#stored-filters","title":"Stored filters","text":"<p>Stored filters are attributes of an entity, and are therefore stored in the database. They are stored as an attribute in the object itself, e.g. filters in dashboards, feeds, TAXII collections, triggers, streams, playbooks.</p>"},{"location":"reference/filters/#create-a-filter","title":"Create a filter","text":"<p>To create a filter, add every key you need using the 'Add filter' select box. It will give you the possible attributes on which you can filter in the current view.</p> <p>A grey box appears and allows to select:</p> <ol> <li>the operator to use, and</li> <li>the values to compare (if the operator is not \"empty\" or \"not_empty\").</li> </ol> <p>You can add as many filters as you want, even use the same key twice with different operators and values.</p> <p>The boolean modes (and/or) are either global (between every attribute filters) or local (between values inside a filter). Both can be switched with a single click, changing the logic of your filtering.</p>"},{"location":"reference/filters/#filters-format","title":"Filters format","text":"<p>Since OpenCTI 5.12, the OpenCTI platform uses a new filter format called <code>FilterGroup</code>. The <code>FilterGroup</code> model enables to do complex filters imbrication with different boolean operators, which extends greatly the filtering capabilities in every part of the platform.</p>"},{"location":"reference/filters/#structure","title":"Structure","text":"<p>The new format used internally by OpenCTI and exposed through its API, can be described as below:</p> <pre><code>// filter formats in OpenCTI &gt;= 5.12\n\ntype FilterGroup = {\n  mode: 'and' | 'or'\n  filters: Filter[]\n  filterGroups: FilterGroup[] // recursive definition\n}\n\ntype Filter  = {\n  key: string[] // or single string (input coercion)\n  values: string[]\n  operator: 'eq' | 'not_eq' | 'gt' // ... and more\n  mode: 'and' | 'or',\n}\n</code></pre>"},{"location":"reference/filters/#properties","title":"Properties","text":"<p>In a given filter group, the <code>mode</code> (<code>and</code> or <code>or</code>) represents the boolean operation between the different <code>filters</code> and <code>filterGroups</code> arrays. The <code>filters</code> and <code>filterGroups</code> arrays are composed of objects of type Filter and FilterGroup.</p> <p>The <code>Filter</code> has 4 properties:</p> <ul> <li>a <code>key</code>, representing the kind of data we want to target (example: <code>objectLabel</code> to filter on labels or <code>createdBy</code> to filter on the author),</li> <li>an array of <code>values</code>, representing the values we want to compare to,</li> <li>an <code>operator</code> representing the operation we want to apply between the <code>key</code> and the <code>values</code>,</li> <li>a <code>mode</code> (<code>and</code> or <code>or</code>) to apply between the values if there are several ones.</li> </ul>"},{"location":"reference/filters/#operators","title":"Operators","text":"<p>The available operators are:</p> Value Meaning Additional information eq equal not_eq different gl greater than against textual values, the alphabetical ordering is used gte greater than or equal against textual values, the alphabetical ordering is used lt lower than against textual values, the alphabetical ordering is used lte lower than or equal against textual values, the alphabetical ordering is used nil empty / no value <code>nil</code> do not require anything inside <code>values</code> not_nil non-empty / any value <code>not_nil</code> do not require anything inside <code>values</code> <p>In addition, there are operators:</p> <ul> <li><code>starts_with</code> / <code>not_starts_with</code> / <code>ends_with</code> / <code>not_ends_with</code> / <code>contains</code> / <code>not contains</code>, available for searching in short string fields (name, value, title, etc.),</li> <li><code>search</code>, available in short string and text fields.</li> </ul> <p>There is a small difference between <code>search</code> and <code>contains</code>. <code>search</code> finds any occurrence of specified words, regardless of order, while \"contains\" specifically looks for the exact sequence of words you provide.</p> <p>Always use single-key filters</p> <p>Multi-key filters are not supported across the platform and are reserved to specific, internal cases.</p>"},{"location":"reference/filters/#examples","title":"Examples","text":"<p>entity_type = 'Report'</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [{\n        key: 'entity_type',\n        values: ['Report'],\n        operator: 'eq',\n        mode: 'or', // useless here because values contains only one value\n    }],\n    filterGroups: [],\n};\n</code></pre> <p>(entity_type = 'Report') AND (label = 'label1' OR 'label2')</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [\n        {\n            key: 'entity_type',\n            values: ['Report'],\n            operator: 'eq',\n            mode: 'or',\n        },\n        {\n            key: 'objectLabel',\n            values: ['label1', 'label2'],\n            operator: 'eq',\n            mode: 'or',\n        }\n    ],\n    filterGroups: [],\n};\n</code></pre> <p>(entity_type = 'Report') AND (confidence &gt; 50 OR marking is empty)</p> <pre><code>filters = {\n    mode: 'and',\n    filters: [\n        {\n            key: 'entity_type',\n            values: ['Report'],\n            operator: 'eq',\n            mode: 'or',\n        }\n    ],\n    filterGroups: [\n        {\n            mode: 'or',\n            filters: [\n                {\n                    key: 'confidence',\n                    values: ['50'],\n                    operator: 'gt',\n                    mode: 'or',\n                },\n                {\n                    key: 'objectMarking',\n                    values: [],\n                    operator: 'nil',\n                    mode: 'or',\n                },\n            ],\n            filterGroups: [],\n        }\n    ],\n};\n</code></pre>"},{"location":"reference/filters/#keys","title":"Keys","text":""},{"location":"reference/filters/#filter-keys-validation","title":"Filter keys validation","text":"<p>Only a specific set of key can be used in the filters.</p> <p>Automatic key checking prevents typing error when constructing filters via the API. If a user write an unhandled key (<code>object-label</code> instead of <code>objectLabel</code> for instance), the API will return an error instead of an empty list. Doing so, we make sure the platform do not provide misleading results.</p>"},{"location":"reference/filters/#regular-filter-keys","title":"Regular filter keys","text":"<p>For an extensive list of available filter keys, refer to the attributes and relations schema definitions.</p> <p>Here are some of the most useful keys as example. NB: X refers here to the filtered entities.</p> <ul> <li><code>objectLabel</code>: label applied on X,</li> <li><code>objectMarking</code>: marking applied on X,</li> <li><code>createdBy</code>: author of X,</li> <li><code>creator_id</code>: technical creator of X,</li> <li><code>created_at</code>: date of creation of X in the platform,</li> <li><code>confidence</code>: confidence of X,</li> <li><code>entity_type</code>: entity type of X ('Report', 'Stix-Cyber-Observable', ...),</li> </ul>"},{"location":"reference/filters/#special-filter-keys","title":"Special filter keys","text":"<p>Some keys do not exist in the schema definition, but are allowed in addition. They describe a special behavior.</p> <p>It is the case for:</p> <ul> <li><code>sightedBy</code>: entities to which X is linked via a STIX sighting relationship,</li> <li><code>workflow_id</code>: status id of the entities, or status template id of the status of the entities,</li> <li><code>representative</code>: entities whose representative (name for reports, value for some observables, composition of the source and target names for a relationship...) matches the filter,</li> <li><code>connectedToId</code>: the listened instances for an instance trigger.</li> </ul> <p>For some keys, negative equality filtering is not supported yet (<code>not_eq</code> operator). For instance, it is the case for:</p> <ul> <li><code>fromId</code></li> <li><code>fromTypes</code></li> <li><code>toId</code></li> <li><code>toTypes</code></li> </ul> <p>The <code>regardingOf</code> filter key has a special format and enables to target the entities having a relationship of a certain type with certain entities. Here is an example of filter to fetch the entities related to the entity X:</p> <pre><code>filters = {\n  mode: 'and',\n  filters: [\n    {\n      key: 'regardingOf',\n      values: [\n        { key: 'id', values: ['id-of-X'] },\n        { key: 'relationship_type', values: ['related-to'] },\n      ],\n    },\n  ],\n  filterGroups: [],\n};\n</code></pre>"},{"location":"reference/filters/#limited-support-in-stream-events-filtering","title":"Limited support in stream events filtering","text":"<p>Filters that are run against the event stream are not using the complete schema definition in terms of filtering keys.</p> <p>This concerns:</p> <ul> <li>Live streams,</li> <li>CSV feeds,</li> <li>TAXII collection,</li> <li>Triggers,</li> <li>Playbooks.</li> </ul> <p>For filters used in this context, only some keys are supported for the moment:</p> <ul> <li><code>confidence</code></li> <li><code>objectAssignee</code></li> <li><code>createdBy</code></li> <li><code>creator</code></li> <li><code>x_opencti_detection</code></li> <li><code>indicator_types</code></li> <li><code>objectLabel</code></li> <li><code>x_opencti_main_observable_type</code></li> <li><code>objectMarking</code></li> <li><code>objects</code></li> <li><code>pattern_type</code></li> <li><code>priority</code></li> <li><code>revoked</code></li> <li><code>severity</code></li> <li><code>x_opencti_score</code></li> <li><code>entity_type</code></li> <li><code>x_opencti_workflow_id</code></li> <li><code>connectedToId</code> (for the instance triggers)</li> <li><code>fromId</code> (the instance in the \"from\" of a relationship)</li> <li><code>fromTypes</code> (the entity type in the \"from\" of a relationship)</li> <li><code>toId</code> (the instance in the \"to\" of a relationship)</li> <li><code>toTypes</code> (the entity type in the \"to\" of a relationship)</li> </ul>"},{"location":"reference/fips/","title":"SSL FIPS 140-2 deployment","text":""},{"location":"reference/fips/#introduction","title":"Introduction","text":"<p>For organizations that need to deploy OpenCTI in a SSL FIPS 140-2 compliant environment, we provide FIPS compliant OpenCTI images for all components of the platform. Please note that you will also need to deploy dependencies (ElasticSearch / OpenSearch, Redis, etc.) with FIPS 140-2 SSL to have the full compliant OpenCTI technological stack.</p> <p>OpenCTI SSL FIPS 140-2 compliant builds</p> <p>The OpenCTI platform, workers and connectors SSL FIPS 140-2 compliant images are based on packaged Alpine Linux with OpenSSL 3 and FIPS mode enabled maintened by the Filigran engineering team.</p>"},{"location":"reference/fips/#dependencies","title":"Dependencies","text":""},{"location":"reference/fips/#aws-native-services-in-fedramp-compliant-environment","title":"AWS Native Services in FedRAMP compliant environment","text":"<p>It is important to remind that OpenCTI is fully compatible with AWS native services and all dependencies are available in both FedRAMP Moderate (East / West) and FedRAMP High (GovCloud) scopes.</p> <ul> <li>Amazon OpenSearch Service (OpenSearch)</li> <li>Amazon ElastiCache (Redis)</li> <li>Amazon MQ (RabbitMQ)</li> <li>Amazon Simple Storage Service (S3 bucket)</li> </ul>"},{"location":"reference/fips/#elasticsearch-opensearch","title":"ElasticSearch / OpenSearch","text":"<p>ElasticSearch is known to be compatible with FIPS 140-2 SSL using the proper JVM. There is a comprehensive guide in the Elastic documentation.</p> <p>Alternatively, please note that Elastic is also providing an ElasticSearch FedRAMP authorized cloud offering.  </p>"},{"location":"reference/fips/#redis","title":"Redis","text":"<p>Redis does not provide FIPS 140-2 SSL compliant Docker images but supports very well custom tls-ciphersuites that can be configured to use the system FIPS 140-2 OpenSSL library. </p> <p>Alternatively, you can use a Stunnel TLS endpoint to ensure encrypted communication between OpenCTI and Redis. There are a few examples available, here or here.</p>"},{"location":"reference/fips/#rabbitmq","title":"RabbitMQ","text":"<p>RabbitMQ does not provide FIPS 140-2 SSL compliant Docker images but, as Redis, supports custom cipher suites. Also, it is confirmed since RabbitMQ version 3.12.5, the associated Erlang build (&gt; 26.1), supports FIPS mode on OpenSSL 3.</p> <p>Alternatively, you can use a Stunnel TLS endpoint to ensure encrypted communication between OpenCTI and RabbitMQ.</p>"},{"location":"reference/fips/#s3-bucket-minio","title":"S3 Bucket / MinIO","text":"<p>If you cannot use an S3 endpoint already deployed in your FIPS 140-2 SSL compliant environment, MinIO provides FIPS 140-2 SSL compliant Docker images which then are very easy to deploy within your environment.</p>"},{"location":"reference/fips/#opencti-stack","title":"OpenCTI stack","text":""},{"location":"reference/fips/#platform","title":"Platform","text":"<p>For the platform, we provide FIPS 140-2 SSL compliant Docker images. Just use the appropriate tag to ensure you are deploying the FIPS compliant version and follow the standard Docker deployment procedure. </p>"},{"location":"reference/fips/#worker","title":"Worker","text":"<p>For the worker, we provide FIPS 140-2 SSL compliant Docker images. Just use the appropriate tag to ensure you are deploying the FIPS compliant version and follow the standard Docker deployment procedure.</p>"},{"location":"reference/fips/#connectors","title":"Connectors","text":"<p>All connectors have FIPS 140-2 SSL compliant Docker images. For each connector you need to deploy, please use the tag <code>{version}-fips</code> instead of <code>{version}</code> and  follow the standard deployment procedure. An example is available on Docker Hub. </p>"},{"location":"reference/streaming/","title":"Data Streaming","text":""},{"location":"reference/streaming/#presentation","title":"Presentation","text":"<p>In order to provide a real time way to consume STIX CTI information, OpenCTI provides data events in a stream that can be consumed to react on creation, update, deletion and merge. This way of getting information out of OpenCTI is highly efficient and already use by some connectors.</p>"},{"location":"reference/streaming/#technology","title":"Technology","text":""},{"location":"reference/streaming/#redis-stream","title":"Redis stream","text":"<p>OpenCTI is currently using REDIS Stream as the technical layer. Each time something is modified in the OpenCTI database, a specific event is added in the stream.</p>"},{"location":"reference/streaming/#sse-protocol","title":"SSE protocol","text":"<p>In order to provide a really easy consuming protocol we decide to provide a SSE (https://fr.wikipedia.org/wiki/Server-sent_events) HTTP URL linked to the standard login system of OpenCTI. Any user with the correct access rights can open and access http://opencti_instance/stream, and open an SSE connection to start receiving live events. You can of course consume directly the stream in Redis, but you will have to manage access and rights directly.</p>"},{"location":"reference/streaming/#events-format","title":"Events format","text":"<pre><code>id: {Event stream id} -&gt; Like 1620249512318-0\nevent: {Event type} -&gt; create / update / delete\ndata: { -&gt; The complete event data\n    version -&gt; The version number of the event\n    type -&gt; The inner type of the event\n    scope -&gt; The scope of the event [internal or external]\n    data: {STIX data} -&gt; The STIX representation of the data.\n    message -&gt; A simple string to easy understand the event\n    origin: {Data Origin} -&gt; Complex object with different information about the origin of the event\n    context: {Event context} -&gt; Complex object with meta information depending of the event type\n}\n</code></pre> <p>It can be used to consume the stream from this specific point.</p>"},{"location":"reference/streaming/#stix-data","title":"STIX data","text":"<p>The current stix data representation is based on the STIX 2.1 format using extension mechanism. Please take a look to the STIX documentation for more information.</p>"},{"location":"reference/streaming/#create","title":"Create","text":"<p>It's simply the data created in STIX format.</p>"},{"location":"reference/streaming/#delete","title":"Delete","text":"<p>It's simply the data in STIX format just before his deletion. You will also find the automated deletions in context due to automatic dependency management.</p> <pre><code>{\n  \"context\": {\n      \"deletions\": [{STIX data}]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#update","title":"Update","text":"<p>This event type publish the complete STIX data information along with patches information. Thanks to the patches, it's possible to rebuild the previous version and easily understand what happens in the update.</p> <p>Patch and reverse_patch follow the official jsonpatch specification. You can find more information on the jsonpatch page</p> <pre><code>{\n  \"context\": {\n      \"patch\": [/* patch operation object */],\n      \"reverse_patch\": [/* patch operation object */]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#merge","title":"Merge","text":"<p>Merge is a combination of an update of the merge targets and deletions of the sources. In this event you will find the same patch and reverse_patch as an update and the list of elements merged into the target in the \"sources\" attribute.</p> <pre><code>{\n  \"context\": {\n      \"patch\": [/* patch operation object */],\n      \"reverse_patch\": [/* patch operation object */],\n      \"sources\": [{STIX data}]\n  }\n}\n</code></pre>"},{"location":"reference/streaming/#stream-types","title":"Stream types","text":"<p>In OpenCTI we propose 2 types of streams.</p>"},{"location":"reference/streaming/#base-stream","title":"Base stream","text":"<p>The stream hosted in /stream url contains all the raw events of the platform, always filtered by the user rights (marking based). It's a technical stream a bit complex to used but very useful for internal processing or some specific connectors like backup/restore.</p> <p>This stream is live by default but if, you want to catchup, you can simply add the <code>from</code> parameter to your query. This parameter accept a timestamp in millisecond and also an event id, e.g. <code>http://localhost/stream?from=1620249512599</code></p> <p>Stream size?</p> <p>The raw stream is really important in the platform and needs te be sized according to the period of retention you want to ensure. More retention you will have, more security about reprocessing the past information you will get. We usually recommand 1 month of retention, that usually match 2 000 000 of events. This limit can be configured with <code>redis:trimming</code> option, please check deployment configuration page.</p>"},{"location":"reference/streaming/#live-stream","title":"Live stream","text":"<p>This stream aims to simplify your usage of the stream through the connectors, providing a way to create stream with specific filters through the UI. After creating this stream, is simply accessible from <code>/stream/{STREAM_ID}</code>.</p> <p>It's very useful for various cases of data externalization, synchronization, like SPLUNK, TANIUM...</p> <p>This stream provides different interesting mechanics:</p> <ul> <li>Stream the initial list of instances matching your filters when connecting based on main database if you use the recover parameter</li> <li>Auto dependencies resolution to guarantee the consistency of the information distributed</li> <li>Automatic events translation depending on the element segregation</li> </ul> <p>If you want to dig in about the internal behavior you can check this complete diagram:</p>"},{"location":"reference/streaming/#general-options","title":"General options","text":"<ul> <li>no-dependencies (query parameter or header, default false). Can be used to prevent the auto dependencies resolution. To be used with caution.</li> <li>listen-delete (query parameter or header, default true). Can be used prevent receive deletion events. To be used with caution.</li> <li>with-inferences (query parameter or header, default false). Can be used to add inferences events (from rule engine) in the stream.</li> </ul>"},{"location":"reference/streaming/#from-and-recover","title":"From and Recover","text":"<p>From and recover are 2 different options that need to be explains.</p> <ul> <li>from (query parameter) is always the parameter that describe the initial date/event_id you want to start from. Can also be setup with request header from or last-event-id</li> <li>recover (query parameter) is an option that let you consume the initial event from the database and not from the stream. Can also be setup with request header recover or recover-date </li> </ul> <p>This difference will be transparent for the consumer but very important to get old information as an initial snapshot. This also let you consume information that is no longer in the stream retention period.</p> <p>The next diagram will help you to understand the concept:</p>"},{"location":"reference/taxonomy/","title":"Taxonomy","text":"<p>In OpenCTI, taxonomies serve as structured classification systems that aid in organizing and categorizing intelligence data. This reference guide provides an exhaustive description of the platform's customizable fields within the taxonomies' framework. Users can modify, add, or delete values within the available vocabularies to tailor the classification system to their specific requirements.</p> <p>For broader documentation on the taxonomies section, please consult the appropriate page.</p>"},{"location":"reference/taxonomy/#vocabularies","title":"Vocabularies","text":"<p>Default values are based on those defined in the STIX standard but can be tailored to better suit the organization's needs.</p> Name Used in Default value Account type vocabulary (account-type-ov) User account facebook, ldap, nis, openid, radius, skype, tacacs, twitter, unix, windows-domain, windows-local Attack motivation vocabulary (attack-motivation-ov) Threat actor group accidental, coercion, dominance, ideology, notoriety, organizational-gain, personal-gain, personal-satisfaction, revenge, unpredictable Attack resource level vocabulary (attack-resource-level-ov) Threat actor group club, contest, government, individual, organization, team Case priority vocabulary (case_priority_ov) Incident response P1, P2, P3, P4 Case severity vocabulary (case_severity_ov) Incident response critical, high, medium, low Channel type vocabulary (channel_type_ov) Channel Facebook, Twitter Collection layers vocabulary (collection_layers_ov) Data source cloud-control-plane, container, host, network, OSINT Event type vocabulary (event_type_ov) Event conference, financial, holiday, international-summit, local-election, national-election, sport-competition Eye color vocabulary (eye_color_ov) Threat actor individual black, blue, brown, green, hazel, other Gender vocabulary (gender_ov) Threat actor individual female, male, nonbinary, other Grouping context vocabulary (grouping_context_ov) Grouping malware-analysis, suspicious-activity, unspecified Hair color vocabulary vocabulary (hair_color_ov) Threat actor individual bald, black, blond, blue, brown, gray, green, other, red Implementation language vocabulary (implementation_language_ov) Malware applescript, bash, c, c++, c#, go, java, javascript, lua, objective-c, perl, php, powershell, python, ruby, scala, swift, typescript, visual-basic, x86-32, x86-64 Incident response type vocabulary (incident_response_type_ov) Incident response data-leak, ransomware Incident severity vocabulary (incident_severity_ov) Incident critical, high, medium, low Incident type vocabulary (incident_type_ov) Incident alert, compromise, cybercrime, data-leak, information-system-disruption, phishing, reputation-damage, typosquatting Indicator type vocabulary (indicator_type_ov) Indicator anomalous-activity, anonymization, attribution, benign, compromised, malicious-activity, unknown Infrastructure type vocabulary (infrastructure_type_ov) Infrastructure amplification, anonymization, botnet, command-and-control, control-system, exfiltration, firewall, hosting-malware, hosting-target-lists, phishing, reconnaissance, routers-switches, staging, unknown, workstation Integrity level vocabulary (integrity_level_ov) Process high, medium, low, system Malware capabilities vocabulary (malware_capabilities_ov) Malware accesses-remote-machines, anti-debugging, anti-disassembly, anti-emulation, anti-memory-forensics, anti-sandbox, anti-vm, captures-input-peripherals, captures-output-peripherals, captures-system-state-data, cleans-traces-of-infection, commits-fraud, communicates-with-c2, compromises-data-availability, compromises-data-integrity, compromises-system-availability, controls-local-machine, degrades-security-software, degrades-system-updates, determines-c2-server, emails-spam, escalates-privileges, evades-av, exfiltrates-data, fingerprints-host, hides-artifacts, hides-executing-code, infects-files, infects-remote-machines, installs-other-components, persists-after-system-reboot, prevents-artifact-access, prevents-artifact-deletion, probes-network-environment, self-modifies, steals-authentication-credentials, violates-system-operational-integrity Malware result vocabulary (malware_result_ov) Malware analysis benign, malicious, suspicious, unknown Malware type vocabulary (malware_type_ov) Malware adware, backdoor, bootkit, bot, ddos, downloader, dropper, exploit-kit, keylogger, ransomware, remote-access-trojan, resource-exploitation, rogue-security-software, rootkit, screen-capture, spyware, trojan, unknown, virus, webshell, wiper, worm Marital status vocabulary (marital_status_ov) Threat actor individual annulled, divorced, domestic_partner, legally_separated, married, never_married, polygamous, separated, single, widowed Note types vocabulary (note_types_ov) Note analysis, assessment, external, feedback, internal Opinion vocabulary (opinion_ov) Opinion agree, disagree, neutral, strongly-agree, strongly-disagree Pattern type vocabulary (pattern_type_ov) Indicator eql, pcre, shodan, sigma, snort, spl, stix, suricata, tanium-signal, yara Permissions vocabulary (permissions_ov) Attack pattern Administrator, root, User Platforms vocabulary (platforms_ov) Data source android, Azure AD, Containers, Control Server, Data Historian, Engineering Workstation, Field Controller/RTU/PLC/IED, Google Workspace, Human-Machine Interface, IaaS, Input/Output Server, iOS, linux, macos, Office 365, PRE, SaaS, Safety Instrumented System/Protection Relay, windows Processor architecture vocabulary (processor_architecture_ov) Malware alpha, arm, ia-64, mips, powerpc, sparc, x86, x86-64 Reliability vocabulary (reliability_ov) Report, Organization A - Completely reliable, B - Usually reliable, C - Fairly reliable, D - Not usually reliable, E - Unreliable, F - Reliability cannot be judged Report types vocabulary (report_types_ov) Report internal-report, threat-report Request for information types vocabulary (request_for_information_types_ov) Request for information none Request for takedown types vocabulary (request_for_takedown_types_ov) Request for takedown brand-abuse, phishing Service status vocabulary (service_status_ov) Process SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED, SERVICE_RUNNING, SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_STOPPED Service type vocabulary (service_type_ov) Process SERVICE_FILE_SYSTEM_DRIVER, SERVICE_KERNEL_DRIVER, SERVICE_WIN32_OWN_PROCESS, SERVICE_WIN32_SHARE_PROCESS Start type vocabulary (start_type_ov) Process SERVICE_AUTO_START, SERVICE_BOOT_START, SERVICE_DEMAND_START, SERVICE_DISABLED, SERVICE_SYSTEM_ALERT Threat actor group role vocabulary (threat_actor_group_role_ov) Threat actor group agent, director, independent, infrastructure-architect, infrastructure-operator, malware-author, sponsor Threat actor group sophistication vocabulary (threat_actor_group_sophistication_ov) Threat actor group advanced, expert, innovator, intermediate, minimal, none, strategic Threat actor group type vocabulary (threat_actor_group_type_ov) Threat actor group activist, competitor, crime-syndicate, criminal, hacker, insider-accidental, insider-disgruntled, nation-state, sensationalist, spy, terrorist, unknown Threat actor individual role vocabulary (threat_actor_individual_role_ov) Threat actor individual agent, director, independent, infrastructure-architect, infrastructure-operator, malware-author, sponsor Threat actor individual sophistication vocabulary (threat_actor_individual_sophistication_ov) Threat actor individual advanced, expert, innovator, intermediate, minimal, none, strategic Threat actor individual type vocabulary (threat_actor_individual_type_ov) Threat actor individual activist, competitor, crime-syndicate, criminal, hacker, insider-accidental, insider-disgruntled, nation-state, sensationalist, spy, terrorist, unknown Tool types vocabulary (tool_types_ov) Tool credential-exploitation, denial-of-service, exploitation, information-gathering, network-capture, remote-access, unknown, vulnerability-scanning <p></p>"},{"location":"reference/taxonomy/#customization","title":"Customization","text":"<p>Users can customize the taxonomies by modifying the available values or adding new ones. These modifications enable users to adapt the classification system to their specific intelligence requirements. Additionally, within each vocabulary list, users have the flexibility to customize the order of the dropdown menu associated with the taxonomy. This feature allows users to prioritize certain values or arrange them in a manner that aligns with their specific classification needs. Additionally, users can track the usage count for each vocabulary, providing insights into the frequency of usage and helping to identify the most relevant and impactful classifications. These customization options empower users to tailor the taxonomy system to their unique intelligence requirements, enhancing the efficiency and effectiveness of intelligence analysis within the OpenCTI platform.</p> <p></p>"},{"location":"reference/usage-telemetry/","title":"Usage telemetry","text":"<p>The application collects statistical data related to its usage and performances.</p> <p>Confidentiality</p> <p>The OpenCTI platform does not collect any information related to threat intelligence knowledge which remains strictly confidential. Also, the collection is strictly anonymous and personally identifiable information is NOT collected (including IP addresses).</p> <p>All data collected is anonymized and aggregated to protect the privacy of individual users, in compliance with all privacy regulations.</p>"},{"location":"reference/usage-telemetry/#purpose-of-the-telemetry","title":"Purpose of the telemetry","text":"<p>The collected data is used for the following purposes:</p> <ul> <li>Improving the functionality and performance of the application.</li> <li>Analyzing user behavior to enhance user experience.</li> <li>Generating aggregated and anonymized statistics for internal and external reporting.</li> </ul>"},{"location":"reference/usage-telemetry/#important-thing-to-know","title":"Important thing to know","text":"<p>The platform send the metrics to the hostname <code>telemetry.filigran.io</code> using the OTLP protocol (over HTTPS). The format of the data is OpenTelemetry JSON.</p> <p>The metrics push is done every 6 hours if OpenCTI was able to connect to the hostname when the telemetry manager is started. Metrics are also written in specific logs files in order to be included in support package</p>"},{"location":"reference/usage-telemetry/#telemetry-metrics","title":"Telemetry metrics","text":"<p>The application collects statistical data related to its usage. Here are an exhaustive list of the collected metrics:</p> <ul> <li>The current platform version</li> <li>The platform unique identifier</li> <li>The platform creation date</li> <li>The number of active users</li> <li>The number of total users</li> <li>The number of nodes in the platform</li> <li>Enterprise Edition status (activated or not)</li> <li>The number of active connectors</li> </ul>"},{"location":"usage/ask-ai/","title":"Ask AI","text":"<p>Enterprise edition</p> <p>Ask AI is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p>"},{"location":"usage/ask-ai/#prerequisites-for-using-ask-ai","title":"Prerequisites for using Ask AI","text":"<p>There are several possibilities for Enterprise Edition customers to use OpenCTI AI endpoints:</p> <ul> <li>Use the Filigran AI Service leveraging our custom AI model using the token given by the support team.</li> <li>Use OpenAI or MistralAI cloud endpoints using your own tokens.</li> <li>Deploy or use local AI endpoints (Filigran can provide you with the custom model).</li> </ul> <p>Please read the configuration documentation</p> <p>Beta Feature</p> <p>Ask AI is a beta feature as we are currently fine-tuning our models. Consider checking important information.</p>"},{"location":"usage/ask-ai/#how-it-works","title":"How it works","text":"<p>Even if in the future, we would like to leverage AI to do RAG, for the moment we are mostly using AI to analyze and produce texts or images, based on data directly sent into the prompt.</p> <p>This means that if you are using Filigran AI endpoint or a local one, your data is never used to re-train or adapt the model and everything relies on a pre-trained and fixed model. When using the <code>Ask AI</code> button in the platform, a prompt is generated with the proper instruction to generate the expected result and use it in the context of the button (in forms, rich text editor etc.).</p>"},{"location":"usage/ask-ai/#filigran-custom-model","title":"Filigran custom model","text":"<p>We are hosting a scalable AI endpoint for all SaaS or On-Prem enterprise edition customers, this endpoint is based on MistralAI with a model that will be adapted over time to be more effective when processing threat intelligence related contents.</p> <p>The model, which is still in beta version, will be adapted in the upcoming months to reach maturity at the end of 2024. It can be shared with on-prem enterprise edition customers under NDA.</p>"},{"location":"usage/ask-ai/#functionalities-of-ask-ai","title":"Functionalities of Ask AI","text":"<p>Ask AI is represented by a dedicated icon wherever on of its functionalities is available to use.</p> <p></p>"},{"location":"usage/ask-ai/#assistance-for-writing-meaningful-content","title":"Assistance for writing meaningful content","text":"<p>Ask AI can assist you for writing better textual content, for example better title, name, description and detailed content of Objects.</p> <ul> <li>Fix spelling &amp; grammar: try to improve the text from a formulation and grammar perspective.  </li> <li>Make it shorter/longer: try to shorten or lengthen the text.</li> <li>Change tone: try to change the tone of the text. You can select if you want the text to be written for Strategic (Management, decision makers), Tactical (for team leaders) or Operational (for technical CTI analysts) audiences.</li> <li>Summarize: try to summarize the text in bullet points.</li> <li>Explain: try to explain the context of the subject's text based on what is available to the LLM.</li> </ul>"},{"location":"usage/ask-ai/#assistance-for-importing-data-from-documents","title":"Assistance for importing data from documents","text":"<p>Fom the Content tab of a Container (Reports, Groupings and Cases), Ask AI can also assist you for importing data contained in uploaded documents into OpenCTI for further exploitation.</p> <ul> <li>Generate report document: Generate a text report based on the knowledge graph (entities and relationships) of this container.</li> <li>Summarize associated files: Generate a summary of the selected files (or all files associated to this container).</li> <li>Try to convert the selected files (or all files associated to this container) in a STIX 2.1 bundle you will then be able to use at your convenience (for example importing it into the platform).</li> </ul> <p></p> <p></p> <p>A short video on the FiligranHQ YouTube channel presents tha capabilities of AskAI: https://www.youtube.com/watch?v=lsP3VVsk5ds.</p>"},{"location":"usage/ask-ai/#improving-generated-elements-of-ask-ai","title":"Improving generated elements of Ask AI","text":"<p>Be aware that the text quality is highly dependent on the capabilities of the associated LLM.</p> <p>That is why every generated text by Ask AI is provided in a dedicated panel, allowing you to verify and rectify any error the LLM could have made.</p>"},{"location":"usage/automation/","title":"Playbooks Automation","text":"<p>Enterprise edition</p> <p>Playbooks automation is available under the \"OpenCTI Enterprise Edition\" license. Please read the dedicated page to have all information.</p> <p>OpenCTI playbooks are flexible automation scenarios which can be fully customized and enabled by platform administrators to enrich, filter and modify the data created or updated in the platform. </p> <p>Playbook automation is accessible in the user interface under Data &gt; Processing &gt; Automation.</p> <p>Right needed</p> <p>You need the \"Manage credentials\" capability to use the Playbooks automation, because you will be able to manipulate data simple users cannot access.</p> <p>You will then be able to:</p> <ul> <li>add labels depending on enrichment results to be used in threat intelligence-driven detection feeds,</li> <li>create reports and cases based on various criteria,</li> <li>trigger enrichments or webhooks in given conditions,</li> <li>modify attributes such as first_seen and last_seen based on other pieces of knowledge,</li> <li>etc.</li> </ul>"},{"location":"usage/automation/#playbook-philosophy","title":"Playbook philosophy","text":"<p>Consider Playbook as a STIX 2.1 bundle pipeline. </p> <p>Initiating with a component listening to a data stream, each subsequent component in the playbook processes a received STIX bundle. These components have the ability to modify the bundle and subsequently transmit the altered result to connected components.</p> <p>In this paradigm, components can send out the STIX 2.1 bundle to multiple components, enabling the development of multiple branches within your playbook.</p> <p>A well-designed playbook end with a component executing an action based on the processed information. For instance, this may involve writing the STIX 2.1 bundle in a data stream.</p> <p>Validate ingestion</p> <p>The STIX bundle processed by the playbook won't be written in the platform without specifying it using the appropriate component, i.e. \"Send for ingestion\".</p>"},{"location":"usage/automation/#create-a-playbook","title":"Create a Playbook","text":"<p>It is possible to create as many playbooks as needed which are running independently. You can give a name and description to each playbook.</p> <p></p> <p>The first step to define in the playbook is the \u201ctriggering event\u201d, which can be any knowledge event (create, update or delete) with customizable filters. To do so, click on the grey rectangle in the center of the workspace and choose the component to \"listen knowledge events\". Configure it with adequate filters. You can use same filters as in other part of the platform.</p> <p></p> <p>Then you have flexible choices for the next steps to:</p> <ul> <li>filter the initial knowledge,</li> <li>enrich data using external sources and internal rules,</li> <li>modify entities and relationships by applying patches,</li> <li>write the data, send notifications, </li> <li>etc.</li> </ul> <p>Do not forget to start your Playbook when ready, with the Start option of the burger button placed near the name of your Playbook.</p> <p>By clicking the burger button of a component, you can replace it by another one.</p> <p>By clicking on the arrow icon in the bottom right corner of a component, you can develop a new branch at the same level.</p> <p>By clicking the \"+\" button on a link between components, you can insert a component between the two.</p>"},{"location":"usage/automation/#components-of-playbooks","title":"Components of playbooks","text":""},{"location":"usage/automation/#log-data-in-standard-output","title":"Log data in standard output","text":"<p>Will write the received STIX 2.1 bundle in platform logs with configurable log level and then send out the STIX 2.1 bundle unmodified.</p>"},{"location":"usage/automation/#send-for-ingestion","title":"Send for ingestion","text":"<p>Will pass the STIX 2.1 bundle to be written in the data stream. This component has no output and should end a branch of your playbook.</p>"},{"location":"usage/automation/#filter-knowledge","title":"Filter Knowledge","text":"<p>Will allow you to define filter and apply it to the received STIX 2.1 bundle. The component has 2 output, one for data matching the filter and one for the remainder.</p> <p>By default, filtering is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#enrich-through-connector","title":"Enrich through connector","text":"<p>Will send the received STIX 2.1 bundle to a compatible enrichment connector and send out the modified bundle.</p>"},{"location":"usage/automation/#manipulate-knowledge","title":"Manipulate knowledge","text":"<p>Will add, replace or remove compatible attribute of the entities contains in the received STIX 2.1 bundle and send out the modified bundle.</p> <p>By default, modification is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#container-wrapper","title":"Container wrapper","text":"<p>Will modify the received STIX 2.1 bundle to include the entities into an container of the type you configured.  By default, wrapping is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all elements in the bundle (elements that might result from enrichment for example).</p>"},{"location":"usage/automation/#share-with-organizations","title":"Share with organizations","text":"<p>Will share every entity in the received STIX 2.1 bundle with Organizations you configured. Your platform need to have declared a platform main organization in Settings/Parameters.</p>"},{"location":"usage/automation/#apply-predefined-rule","title":"Apply predefined rule","text":"<p>Will apply a complex automation built-in rule. This kind of rule might impact performance. Current rules are:</p> <ul> <li>First/Last seen computing extension from report publication date: will populate first seen and last seen date of entities contained in the report based on its publication date,</li> <li>Resolve indicators based on observables (add in bundle): will retrieve all indicators linked to the bundle's observables from the database,</li> <li>Resolve observables an indicator is based on (add in bundle): retrieve all observables linked to the bundle's indicator from the database,</li> <li>Resolve container references (add in bundle): will add to the bundle all the relationships and entities the container contains (if the entity having triggered the playbook is not a container, the output of this component will be empty),</li> <li>Resolve neighbors relations and entities (add in bundle): will add to the bundle all relations of the entity having triggered the playbook, as well as all entities at the end of these relations, i.e. the \"first neighbors\" (if the entity is a container, the output of this component will be empty).</li> </ul>"},{"location":"usage/automation/#send-to-notifier","title":"Send to notifier","text":"<p>Will generate a Notification each time a STIX 2.1 bundle is received.</p>"},{"location":"usage/automation/#promote-observable-to-indicator","title":"Promote observable to indicator","text":"<p>Will generate indicator based on observables contained in the received STIX 2.1 bundle. </p> <p>By default, it is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all observables in the bundle (e.g. observables that might result from predefined rule).</p> <p>You can also add all indicators and relationships generated by this component in the entity having triggered the playbook, if this entity is a container.</p>"},{"location":"usage/automation/#extract-observables-from-indicator","title":"Extract observables from indicator","text":"<p>Will extract observables based on indicators contained in the received STIX 2.1 bundle. </p> <p>By default, it is applied to entities having triggered the playbook. You can toggle the corresponding option to apply it to all indicators in the bundle (e.g. indicators that might result from enrichment.</p> <p>You can also add all observables and relationships generated by this component in the entity having triggered the playbook, if this entity is a container.</p>"},{"location":"usage/automation/#reduce-knowledge","title":"Reduce Knowledge","text":"<p>Will elagate the received STIX 2.1 bundle based on the configured filter.</p>"},{"location":"usage/automation/#monitor-playbook-activity","title":"Monitor playbook activity","text":"<p>At the top right of the interface, you can access execution trace of your playbook and consult the raw data after every step of your playbook execution.</p> <p></p>"},{"location":"usage/background-tasks/","title":"Background tasks","text":"<p>Three types of tasks are done in the background:</p> <ul> <li>rule tasks,</li> <li>knowledge tasks,</li> <li>user tasks.</li> </ul> <p>Rule tasks can be seen and activated in Settings &gt; Customization &gt; Rules engine. Knowledge and user tasks can be seen and managed in Data &gt; Background Tasks. The scope of each task is indicated.</p> <p></p>"},{"location":"usage/background-tasks/#rule-tasks","title":"Rule tasks","text":"<p>If a rule task is enabled, it leads to the scan of the whole platform data and the creation of entities or relationships in case a configuration corresponds to the tasks rules. The created data are called 'inferred data'. Each time an event occurs in the platform, the rule engine checks if inferred data should be updated/created/deleted.</p>"},{"location":"usage/background-tasks/#knowledge-tasks","title":"Knowledge tasks","text":"<p>Knowledge tasks are background tasks updating or deleting entities and correspond to mass operations on these data. To create one, select entities via the checkboxes in an entity list, and choose the action to perform via the toolbar.</p>"},{"location":"usage/background-tasks/#rights","title":"Rights","text":"<ul> <li>To create a knowledge task, the user should have the capability to Update Knowledge (or the capability to delete knowledge if the task action is a deletion).</li> <li>To see a knowledge task in the Background task section, the user should be the creator of the task, or have the KNOWLEDGE capability.</li> <li>To delete a knowledge task from the Background task section, the user should be the creator of the task, or have the KNOWLEDGE_UPDATE capability.</li> </ul>"},{"location":"usage/background-tasks/#user-tasks","title":"User tasks","text":"<p>User tasks are background tasks updating or deleting notifications. It can be done from the Notification section, by selecting several notifications via the checkboxes, and choosing an action via the toolbar.</p>"},{"location":"usage/background-tasks/#rights_1","title":"Rights","text":"<ul> <li>A user can create a user task on its own notifications only.</li> <li>To see or delete a user task, the user should be the creator of the task or have the SET_ACCESS capability.</li> </ul>"},{"location":"usage/case-management/","title":"Case management","text":""},{"location":"usage/case-management/#why-case-management","title":"Why Case management?","text":"<p>Compiling CTI data in one place, deduplicate and correlate to transform it into Intelligence is very important. But ultimately, you need to act based on this Intelligence. Some situations will need to be taken care of, like cybersecurity incidents, requests for information or requests for takedown. Some actions will then need to be traced, to be coordinated and oversaw. Some actions will include feedback and content delivery.</p> <p>OpenCTI includes Cases to allow organizations to manage situations and organize their team's work. Better, by doing Case management in OpenCTI, you handle your cases with all the context and Intelligence you need, at hand.</p>"},{"location":"usage/case-management/#how-to-manage-your-case-in-opencti","title":"How to manage your Case in OpenCTI?","text":"<p>Multiple situations can be modelize in OpenCTI as a Case, either an Incident Response, a Request for Takedown or a Request for Information.</p> <p></p> <p>All Cases can contain any entities and relationships you need to represent the Intelligence context related to the situation. At the beginning of your case, you may find yourself with only some Observables sighted in a system. At the end, you may have Indicators, Threat Actor, impacted systems, attack patterns. All representing your findings, ready to be presented and exported as graph, pdf report, timeline, etc.</p> <p></p> <p>Some Cases may need some collaborative work and specific Tasks to be performed by people that have the skillset for. OpenCTI allows you to associate <code>Tasks</code> in your Cases and assign them to users in the platform. As some type of situation may need the same tasks to be done, it is also possible to pre-define lists of tasks to be applied on your case. You can define these lists by accessing the Settings/Taxonomies/Case templates panel. Then you just need to add it from the overview of your desire Case.</p> <p>Tip: A user can have a custom dashboard showing him all the tasks that have been assigned to him.</p> <p></p> <p>As with other objects in OpenCTI, you can also leverage the <code>Notes</code> to add some investigation and analysis related comments, helping you shaping up the content of your case with unstructured data and trace all the work that have been done.</p> <p>You can also use <code>Opinions</code> to collect how the Case has been handled, helping you to build Lessons Learned.</p> <p></p> <p>To trace the evolution of your Case and define specific resolution worflows, you can use the <code>Status</code> (that can be define in Settings/Taxonomies/Status templates).</p> <p>At the end of your Case, you will certainly want to report on what have been done. OpenCTI allows you to export the content of the Case in a simple but customizable PDF (currently in refactor). But of course, your company have its own documents' templates, right? With OpenCTI, you will be able to include some nice graphics in it. For example, a Matrix view of the attacker attack pattern or even a graph display of how things are connected. </p> <p>Also, we are currently working a more meaningfull Timeline view that will be possible to export too.</p>"},{"location":"usage/case-management/#use-case-example-a-suspicious-observable-is-sighted-by-a-defense-system-is-it-important","title":"Use case example: A suspicious observable is sighted by a defense system. Is it important?","text":"<ul> <li>Daily, your SIEM and EDR are feeded Indicators of Compromise from your OpenCTI instance. </li> <li>Today, your SIEM have sighted the domain name \"bad.com\" matching one of them. Its alert has been transfered to OpenCTI and have created a <code>Sighting</code> relationship between your System \"SIEM permiter A\" and the Observable \"bad.com\". </li> <li>You are alerted immediatly, because you have activated the inference rule creating a corresponding <code>Incident</code> in this situation, and you have created an alert based on new Incident that send you email <code>notification</code> and Teams message (webhook).</li> <li>In OpenCTI, you can clearly see the link between the alerting System, the sighted Observable and the corresponding Indicator. Better, you can also see all the context of the Indicator. It is linked to a notorious and recent phishing <code>campaign</code> targeting your activity <code>sector</code>. \"bad.com\" is clearly something to investigate ASAP.</li> <li>You quickly select all the context you have found, and add it to a new <code>Incident response</code>case. You position the priority to High, regarding the context, and the severity to Low, as you don't know yet if someone really interact with \"bad.com\"</li> <li>You also assign the case to one of your collegue, on duty for investigative work. To guide him, you also create a <code>Task</code> in your case for verifying if an actual interaction happened with \"bad.com\".</li> </ul>"},{"location":"usage/containers/","title":"Containers","text":""},{"location":"usage/containers/#stix-standard","title":"STIX standard","text":""},{"location":"usage/containers/#definition","title":"Definition","text":"<p>In the STIX 2.1 standard, some STIX Domain Objects (SDO) can be considered as \"container of knowledge\", using the <code>object_refs</code> attribute to refer multiple other objects as nested references. In <code>object_refs</code>, it is possible to refer to entities and relationships. </p>"},{"location":"usage/containers/#example","title":"Example","text":"<pre><code>{\n   \"type\": \"report\",\n   \"spec_version\": \"2.1\",\n   \"id\": \"report--84e4d88f-44ea-4bcd-bbf3-b2c1c320bcb3\",\n   \"created_by_ref\": \"identity--a463ffb3-1bd9-4d94-b02d-74e4f1658283\",\n   \"created\": \"2015-12-21T19:59:11.000Z\",\n   \"modified\": \"2015-12-21T19:59:11.000Z\",\n   \"name\": \"The Black Vine Cyberespionage Group\",\n   \"description\": \"A simple report with an indicator and campaign\",\n   \"published\": \"2016-01-20T17:00:00.000Z\",\n   \"report_types\": [\"campaign\"],\n   \"object_refs\": [\n      \"indicator--26ffb872-1dd9-446e-b6f5-d58527e5b5d2\",\n      \"campaign--83422c77-904c-4dc1-aff5-5c38f3a2c55c\",\n      \"relationship--f82356ae-fe6c-437c-9c24-6b64314ae68a\"\n   ]\n}\n</code></pre> <p>In the previous example, we have a nested reference to 3 other objects:</p> <pre><code>\"object_refs\": [\n   \"indicator--26ffb872-1dd9-446e-b6f5-d58527e5b5d2\",\n   \"campaign--83422c77-904c-4dc1-aff5-5c38f3a2c55c\",\n   \"relationship--f82356ae-fe6c-437c-9c24-6b64314ae68a\"\n]\n</code></pre>"},{"location":"usage/containers/#implementation","title":"Implementation","text":""},{"location":"usage/containers/#types-of-container","title":"Types of container","text":"<p>In OpenCTI, containers are displayed differently than other entities, because they contain pieces of knowledge. Here is the list of containers in the platform:</p> Type of entity STIX standard Description Report Native Reports are collections of threat intelligence focused on one or more topics, such as a description of a threat actor, malware, or attack technique, including context and related details. Grouping Native A Grouping object explicitly asserts that the referenced STIX Objects have a shared context, unlike a STIX Bundle (which explicitly conveys no context). Observed Data Native Observed Data conveys information about cyber security related entities such as files, systems, and networks using the STIX Cyber-observable Objects (SCOs). Note Native A Note is intended to convey informative text to provide further context and/or to provide additional analysis not contained in the STIX Objects. Opinion Native An Opinion is an assessment of the correctness of the information in a STIX Object produced by a different entity. Case Extension A case whether an Incident Response, a Request for Information or a Request for Takedown is used to convey an epic with a set of tasks. Task Extension A task, generally used in the context of a case, is intended to convey information about something that must be done in a limited timeframe."},{"location":"usage/containers/#containers-behavior","title":"Containers behavior","text":"<p>In the platform, it is always possible to visualize the list of entities and/or observables referenced in a container (<code>Container &gt; Entities or Observables</code>) but also to add / remove entities from the container.</p> <p></p> <p>As containers can also contain relationships, which are generally linked to the other entities in the container, it is also possible to visualize the container as a graph (<code>Container &gt; Knowledge</code>)</p> <p></p>"},{"location":"usage/containers/#containers-of-an-entity-or-a-relationship","title":"Containers of an entity or a relationship","text":"<p>On the entity or the relationship side, you can always find all containers where the object is contained using the top menu <code>Analysis</code>:</p> <p></p> <p>In all containers list, you can also filter containers based on one or multiple contained object(s):</p> <p></p>"},{"location":"usage/dashboards-share/","title":"Share custom dashboards","text":"<p>OpenCTI provides a simple way to share a visualisation of a custom dashboard to anyone, even for people that are outside of the platform. We call those visualisations: public dashboards.</p> <p>Public dashboards are a snapshot of a custom dashboard at a specific moment of time.  By this way you can share a version of a custom dashboard, then modify your custom dashboard without worrying about the impact on public dashboards you have created.</p> <p>On the contrary, if you want that your public dashboard is updated with the last version of the associated custom dashboard, you can do it with few clicks by recreating a public dashboard using the same name of the one to update.</p> <p>To be able to share custom dashboards you need to have the Manage data sharing &amp; ingestion capability.</p>"},{"location":"usage/dashboards-share/#create-a-public-dashboard","title":"Create a public dashboard","text":"<p>On the top-right of your custom dashboard page you will find a button that will open a panel to manage the public dashboards associated to this custom dashboard.</p> <p></p> <p>In this panel you will find two parts: - At the top you have a form allowing you to create public dashboards, - And below, the list of the public dashboards you have created.</p> <p></p>"},{"location":"usage/dashboards-share/#form-to-create-a-new-public-dashboard","title":"Form to create a new public dashboard","text":"<p>First you need to specify a name for your public dashboard. This name will be displayed on the dashboard page. The name is also used to generate an ID for your public dashboard that will be used in the URL to access the dashboard.</p> <p>The ID is generated as follow: replace all spaces with symbol <code>-</code> and remove special characters. This ID also needs to be unique in the platform as it is used in the URL to access the dashboard.</p> <p></p> <p>Then you can choose if the public dashboard is enabled or not. A disabled dashboard means that you cannot access the public dashboard through the custom URL. But you can still manage it from this panel.</p> <p></p> <p>Finally you choose the max level of marking definitions for the data to be displayed in the public dashboard. For example if you choose <code>TLP:AMBER</code> then the data fetched by the widgets inside the public dashboard will be at maximum AMBER, you won't retrieved data with RED marking definition.</p> <p>Also note that the list of marking definitions you can see is based on your current marking access on the platform and the maximum sharable marking definitions defined by the admin of the platform:</p> <p>As a platform administrator, you can define, for each type of marking definition, Maximum marking definitions shareable to be  shared through Public Dashboard, regardless of the definition set by users in their public dashboard.  This configuration is accessible in <code>settings &gt; security &gt; policies</code> (this step is mandatory for creating public  dashboards to ensure control over data sharing).</p> <p></p>"},{"location":"usage/dashboards-share/#list-of-the-public-dashboards","title":"List of the public dashboards","text":"<p>When you have created a public dashboard, it will appear in the list below the form.</p> <p></p> <p>In this list each item represents a public dashboard you have created. For each you can see its name, path of the URL, max marking definitions, the date of creation, the status to know if the dashboard is enabled or not and some actions.</p> <p>The possible actions are: copy the link of the public dashboard, disable or enable the dashboard and delete the dashboard.</p> <p>To share a public dashboard just copy the link and give the URL to the person you want to share with. The dashboard will be visible even if the person is not connected to OpenCTI.</p>"},{"location":"usage/dashboards/","title":"Custom dashboards","text":"<p>OpenCTI provides an adaptable and entirely customizable dashboard functionality. The flexibility of OpenCTI's dashboard ensures a tailored and insightful visualization of data, fostering a comprehensive understanding of the platform's knowledge, relationships, and activities.</p>"},{"location":"usage/dashboards/#dashboard-overview","title":"Dashboard overview","text":"<p>You have the flexibility to tailor the arrangement of widgets on your dashboard, optimizing organization and workflow efficiency. Widgets can be intuitively placed to highlight key information. Additionally, you can resize widgets from the bottom right corner based on the importance of the information, enabling adaptation to specific analytical needs. This technical flexibility ensures a fluid, visually optimized user experience.</p> <p>Moreover, the top banner of the dashboard offers a convenient feature to configure the timeframe for displayed data. This can be accomplished through the selection of a relative time period, such as \"Last 7 days\", or by specifying fixed \"Start\" and \"End\" dates, allowing users to precisely control the temporal scope of the displayed information.</p> <p></p> <p></p>"},{"location":"usage/dashboards/#access-control","title":"Access control","text":"<p>In OpenCTI, the power to create custom dashboards comes with a flexible access control system, allowing users to tailor visibility and rights according to their collaborative needs.</p> <p>When a user crafts a personalized dashboard, by default, it remains visible only to the dashboard creator. At this stage, the creator holds administrative access rights. However, they can extend access and rights to others using the \"Manage access\" button, denoted by a locker icon, located at the top right of the dashboard page.</p> <p></p> <p>Levels of access:</p> <ul> <li>View: Access to view the dashboard. </li> <li>Edit: View + Permission to modify and update the dashboard and its widgets. </li> <li>Manage: Edit + Ability to delete the dashboard and to control user access and rights.</li> </ul> <p>It's crucial to emphasize that at least one user must retain admin access to ensure ongoing management capabilities for the dashboard.</p> <p> </p> <p>Knowledge access restriction</p> <p>The platform's data access restrictions also apply to dashboards. The data displayed in the widgets is subject to the user's access rights within the platform. Therefore, an admin user will not see the same results in the widgets as a user with limited access, such as viewing only TLP:CLEAR data (assuming the platform contains data beyond TLP:CLEAR). </p>"},{"location":"usage/dashboards/#share-dashboard-and-widget-configurations","title":"Share dashboard and widget configurations","text":"<p>OpenCTI provides functionality for exporting, importing and duplicating dashboard and widget configurations, facilitating the seamless transfer of customized dashboard setups between instances or users.</p>"},{"location":"usage/dashboards/#export","title":"Export","text":"<p>Dashboards can be exported from either the custom dashboards list or the dashboard view. </p> <p>To export a dashboard configuration from the custom dashboards list:</p> <ol> <li>Click on the burger menu button at the end of the dashboard line.</li> <li>Select <code>Export</code>.</li> </ol> <p></p> <p>To export a widget, the same mechanism is used, but from the burger menu button in the upper right-hand corner of the widget.</p> <p></p> <p>To export a dashboard configuration from the dashboard view:</p> <ol> <li>Navigate to the desired dashboard.</li> <li>Click on the <code>Export</code> button (file with an arrow pointing to the top right corner) located in the top-right corner of the dashboard.</li> </ol> <p></p>"},{"location":"usage/dashboards/#configuration-file","title":"Configuration file","text":"<p>The dashboard configuration will be saved as a JSON file, with the title formatted as <code>[YYYYMMDD]_octi_dashboard_[dashboard title]</code>. The expected configuration file content is as follows:</p> <pre><code>{\n  \"openCTI_version\": \"5.12.0\",\n  \"type\": \"dashboard\",\n  \"configuration\": {\n    \"name\": \"My dashboard title\",\n    \"manifest\": \"eyJ3aWRn(...)uZmlnIjp7fX0=\"\n  }\n}\n</code></pre> <p>The widget configuration will be saved as a JSON file, with the title formatted as <code>[YYYYMMDD]_octi_widget_[widget view]</code>. The expected configuration file content is as follows:</p> <pre><code>{\n  \"openCTI_version\": \"5.12.0\",\n  \"type\": \"widget\",\n  \"configuration\": \"eyJ0eXB(...)iOmZhbHNlfX0=\"\n}\n</code></pre> <p>Source platform-related filters</p> <p>When exporting a dashboard or widget configuration, all filters will be exported as is. Filters on objects that do not exist in the receiving platform will need manual deletion after import. Filters to be deleted can be identified by their \"delete\" barred value.</p> <p></p>"},{"location":"usage/dashboards/#import","title":"Import","text":"<p>Dashboards can be imported from the custom dashboards list:</p> <ol> <li>Hover over the Add button (+) in the right bottom corner.</li> <li>Click on the <code>Import dashboard</code> button (cloud with an upward arrow).</li> <li>Select your file.</li> </ol> <p></p> <p>To import a widget, the same mechanism is used, but from a dashboard view.</p> <p></p> <p>Configuration compatibility</p> <p>Only JSON files with the required properties will be accepted, including \"openCTI_version: [5.12.0 and above]\", \"type: [dashboard|widget]\", and a \"configuration\". This applies to both dashboards and widgets configurations.</p>"},{"location":"usage/dashboards/#duplicate","title":"Duplicate","text":"<p>Dashboards can be duplicated from either the custom dashboards list or the dashboard view.</p> <p>To duplicate a dashboard from the custom dashboards list:</p> <ol> <li>Click on the burger menu button at the end of the dashboard line.</li> <li>Select <code>Duplicate</code>.</li> </ol> <p>To duplicate a widget, the same mechanism is used, but from the burger menu button in the upper right-hand corner of the widget.</p> <p>To duplicate a dashboard from the dashboard view:</p> <ol> <li>Navigate to the desired dashboard.</li> <li>Click on the <code>Duplicate the dashboard</code> button (two stacked sheets) located in the top-right corner of the dashboard.</li> </ol> <p></p> <p>Upon successful duplication, a confirmation message is displayed for a short duration, accompanied by a link for easy access to the new dashboard view. Nevertheless, the new dashboard can still be found in the dashboards list.</p> <p></p> <p>Dashboard access</p> <p>The user importing or duplicating a dashboard becomes the only one with access to it. Then, access can be managed as usual.</p>"},{"location":"usage/data-model/","title":"Data model","text":""},{"location":"usage/data-model/#introduction","title":"Introduction","text":"<p>The OpenCTI core design relies on the concept of a knowledge graph, where you have two different kinds of object:</p> <ol> <li>Nodes are used to describe <code>entities</code>, which have some <code>properties</code> or <code>attributes</code>.</li> <li>Edges are used to describe <code>relationships</code>, which are created between two <code>entity</code> nodes and have some <code>properties</code> or <code>attributes</code>.</li> </ol> <p>Example</p> <p>An example would be that the entity <code>APT28</code> has a relationship <code>uses</code> to the malware entity <code>Drovorub</code>.</p>"},{"location":"usage/data-model/#standard","title":"Standard","text":""},{"location":"usage/data-model/#the-stix-model","title":"The STIX model","text":"<p>To enable a unified approach in the description of threat intelligence knowledge as well as importing and exporting data, the OpenCTI data model is based on the STIX 2.1 standard. Thus we highly recommend to take a look to the STIX Introductory Walkthrough and to the different kinds of STIX relationships to get a better understanding of how OpenCTI works.</p> <p>Some more important STIX naming shortcuts are:</p> <ul> <li>STIX Domain Objects (SDO): Attack Patterns, Malware, Threat Actors, etc.</li> <li>STIX Cyber Observable (SCO): IP Addresses, domain names, hashes, etc.</li> <li>STIX Relationship Object (SRO): Relationships, Sightings</li> </ul> <p></p>"},{"location":"usage/data-model/#extensions","title":"Extensions","text":"<p>In some cases, the model has been extended to be able to:</p> <ul> <li>Support more types of SCOs to modelize information systems such as cryptocurrency wallets, user agents, etc.</li> <li>Support more types of SDOs to modelize disinformation and cybercrime such as channels, events, narrative, etc.</li> <li>Support more types of SROs to extend the new SDOs such as<code>amplifies</code>, <code>publishes</code>, etc.</li> </ul>"},{"location":"usage/data-model/#implementation-in-the-platform","title":"Implementation in the platform","text":""},{"location":"usage/data-model/#diagram-of-types","title":"Diagram of types","text":"<p>You can find below the digram of all types of entities and relationships available in OpenCTI.</p>"},{"location":"usage/data-model/#attributes-and-properties","title":"Attributes and properties","text":"<p>To get a comprehensive list of available properties for a given type of entity or relationship, you can use the GraphQL playground schema available in your \"Profile &gt; Playground\". Then you can click on schema. You can for instance search for the keyword <code>IntrusionSet</code>:</p> <p></p>"},{"location":"usage/dates/","title":"Meaning of dates","text":"<p>In OpenCTI, entities can contain various dates, each representing different types of information. The available dates vary depending on the entity types.</p>"},{"location":"usage/dates/#dates","title":"Dates","text":"<p>In OpenCTI, dates play a crucial role in understanding the context and history of entities. Here's a breakdown of the different dates you might encounter in the platform:</p> <ul> <li>\u201cPlatform creation date\u201d: This date signifies the moment the entity was created within OpenCTI. On the API side, this timestamp corresponds to the <code>created_at</code> field. It reflects the initiation of the entity within the OpenCTI environment.</li> <li>\u201cOriginal creation date\u201d: This date reflects the original creation date of the data on the source's side. It becomes relevant if the source provides this information and if the connector responsible for importing the data takes it into account. In cases where the source date is unavailable or not considered, this date defaults to the import date (i.e. the \u201cPlatform creation date\u201d). On the API side, this timestamp corresponds to the <code>created</code> field.</li> <li>\u201cModification date\u201d: This date captures the most recent modification made to the entity, whether a connector automatically modifies it or a user manually edits the entity. On the API side, this timestamp corresponds to the <code>updated_at</code> field. It serves as a reference point for tracking the latest changes made to the entity.</li> <li>Date not shown on GUI: There is an additional date which is not visible on the entity in the GUI. This date is the <code>modified</code> field on the API. This date reflects the original update date of the data on the source's side. The difference between <code>modified</code> and <code>updated_at</code> is identical to the difference between <code>created</code> and <code>created_at</code>.</li> </ul> <p></p> <p>Understanding these dates is pivotal for contextualizing the information within OpenCTI, ensuring a comprehensive view of entity history and evolution.</p>"},{"location":"usage/dates/#date-types","title":"Date types","text":""},{"location":"usage/dates/#technical-dates","title":"Technical dates","text":"<p>The technical dates refer to the dates directly associated to data management within the platform. The API fields corresponding to technical dates are:</p> <ul> <li>created_at: Indicates the date and time when the entity was created in the platform.</li> <li>updated_at: Represents the date and time of the most recent update to the entity in the platform.</li> </ul>"},{"location":"usage/dates/#functional-dates","title":"Functional dates","text":"<p>The functional dates are the dates functionally significant, often indicating specific events or milestones. The API fields corresponding to functional dates are:</p> <ul> <li>created: Denotes the date and time when the entity was created on the source's side.</li> <li>modified: Represents the date and time of the most recent modification to the entity on the source's side.</li> <li>start_time: Indicates the start date and time associated with a relationship.</li> <li>stop_time: Indicates the stop date and time associated with a relationship.</li> <li>first_seen: Represents the initial date and time when the entity/activity was observed.</li> <li>last_seen: Represents the most recent date and time when the entity/activity was observed.</li> </ul>"},{"location":"usage/deduplication/","title":"Deduplication","text":"<p>One of the core concept of the OpenCTI knowledge graph is all underlying mechanisms implemented to accurately de-duplicate and consolidate (aka. <code>upserting</code>) information about entities and relationships.</p>"},{"location":"usage/deduplication/#creation-behavior","title":"Creation behavior","text":"<p>When an object is created in the platform, whether manually by a user or automatically by the connectors / workers chain, the platform checks if something already exist based on some properties of the object. If the object already exists, it will return the existing object and, in some cases, update it as well.</p> <p>Technically, OpenCTI generates deterministic IDs based on the listed properties below to prevent duplicate (aka \"ID Contributing Properties\"). Also, it is important to note that there is a special link between <code>name</code> and <code>aliases</code> leading to not have entities with overlapping aliases or an alias already used in the name of another entity.</p>"},{"location":"usage/deduplication/#entities","title":"Entities","text":"Type Attributes Area (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Attack Pattern (<code>name</code> OR <code>alias</code>) AND optional <code>x_mitre_id</code> Campaign <code>name</code> OR <code>alias</code> Channel <code>name</code> OR <code>alias</code> City (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Country (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Course Of Action (<code>name</code> OR <code>alias</code>) AND optional <code>x_mitre_id</code> Data Component <code>name</code> OR <code>alias</code> Data Source <code>name</code> OR <code>alias</code> Event <code>name</code> OR <code>alias</code> Feedback Case <code>name</code> AND <code>created</code> (date) Grouping <code>name</code> AND <code>context</code> Incident <code>name</code> OR <code>alias</code> Incident Response Case <code>name</code> OR <code>alias</code> Indicator <code>pattern</code> OR <code>alias</code> Individual (<code>name</code> OR <code>x_opencti_alias</code>) and <code>identity_class</code> Infrastructure <code>name</code> OR <code>alias</code> Intrusion Set <code>name</code> OR <code>alias</code> Language <code>name</code> OR <code>alias</code> Malware <code>name</code> OR <code>alias</code> Malware Analysis <code>name</code> OR <code>alias</code> Narrative <code>name</code> OR <code>alias</code> Note None Observed Data <code>name</code> OR <code>alias</code> Opinion None Organization (<code>name</code> OR <code>x_opencti_alias</code>) and <code>identity_class</code> Position (<code>name</code> OR <code>x_opencti_alias</code>) AND <code>x_opencti_location_type</code> Region <code>name</code> OR <code>alias</code> Report <code>name</code> AND <code>published</code> (date) RFI Case <code>name</code> AND <code>created</code> (date) RFT Case <code>name</code> AND <code>created</code> (date) Sector (<code>name</code> OR <code>alias</code>) and <code>identity_class</code> Task None Threat Actor <code>name</code> OR <code>alias</code> Tool <code>name</code> OR <code>alias</code> Vulnerability <code>name</code> OR <code>alias</code> <p>Names and aliases management</p> <p>The name and aliases of an entity define a set of unique values, so it's not possible to have the name equal to an alias and vice versa.</p>"},{"location":"usage/deduplication/#relationships","title":"Relationships","text":"<p>The deduplication process of relationships is based on the following criterias:</p> <ul> <li>Type</li> <li>Source</li> <li>Target</li> <li>Start time between -30 days / + 30 days</li> <li>Stop time between -30 days / + 30 days</li> </ul>"},{"location":"usage/deduplication/#observables","title":"Observables","text":"<p>For STIX Cyber Observables, OpenCTI also generate deterministic IDs based on the STIX specification using the \"ID Contributing Properties\" defined for each type of observable.</p>"},{"location":"usage/deduplication/#update-behavior","title":"Update behavior","text":"<p>In cases where an entity already exists in the platform, incoming creations can trigger updates to the existing entity's attributes. This logic has been implemented to converge the knowledge base towards the highest confidence and quality levels for both entities and relationships.</p> <p>To understand in details how the deduplication mechanism works in context of the maximum confidence level, you can navigate through this diagram (section deduplication):</p>"},{"location":"usage/delete-restore/","title":"Delete and restore knowledge","text":"<p>Knowledge can be deleted from OpenCTI either in an overview of an object or using background tasks When an object is deleted, all its relationships and references to other objects are also deleted. </p> <p>The deletion event is written to the stream, to trigger automated playbooks or synchronize another platform.</p> <p>Since OpenCTI 6.1, a record of the deleted objects is kept for a given period of a time, allowing to restore them on demand. This does not impact the stream events or other side effect of the deletion: the object is still deleted.</p>"},{"location":"usage/delete-restore/#trash","title":"Trash","text":"<p>A view called \"Trash\" displays all \"delete\" operations, entities and relationships alike.</p> <p></p> <p>A delete operation contains not only the entity or relationship that has been deleted, but also all the relationships and references from (to) this main object to (from) other elements in the platform.</p> <p>You can sort, filter or search this table using the usual UI controls. You are limited to the type of object, their representation (most of the time, the name of the object), the user who deleted the object, the date and time of deletion and the marking of the object.</p> <p>Note that the delete operations (i.e. the entries in this table view) inherit the marking of the main entity that was deleted, and thus follow the same access restriction as the object that was deleted.</p> <p>You can individually restore or permanently delete an object from the trash view using the burger menu at the end of the line.</p> <p></p> <p>Alternatively, you can use the checkboxes at the start of the line to select a subset of deleted objects, and trigger a background task to restore or permanently delete them by batch.</p>"},{"location":"usage/delete-restore/#restore","title":"Restore","text":"<p>Restoring an element creates it again in the platform with the same information it had before its deletion. It also restores all the relationships from or to this object, that have been also deleted during the deletion operation. If the object had attached files (uploaded or exported), they are also restored.</p> <p></p>"},{"location":"usage/delete-restore/#permanent-delete","title":"Permanent delete","text":"<p>From the Trash panel, it is also possible to delete permanently the object, its relationships, and attached files.</p> <p></p>"},{"location":"usage/delete-restore/#trash-retention","title":"Trash retention","text":"<p>Deleted objects are kept in trash during a fixed period of time (7 days by default), then they are permanently deleted by the trash manager.</p>"},{"location":"usage/delete-restore/#limitations","title":"Limitations","text":"<p>When it comes to restoring a deleted object from the trash, the current implementation shows several limitations.  First and foremost, if an object in the trash has lost a relationship dependency (i.e. the other side of a relationship from or to this object is no longer in live database), you will not be able to restore the object.</p> <p></p> <p>In such case, if the missing dependency is in the trash too, you can manually restore this dependency first and then retry.</p> <p>If the missing dependency has been permanently deleted, the object cannot be recovered.</p> <p></p> <p>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</p>"},{"location":"usage/enrichment/","title":"Enrichment connectors","text":"<p>Enriching the data within the OpenCTI platform is made seamlessly through the integration of enrichment connectors. These connectors facilitate the retrieval of additional data from external sources or portals.</p>"},{"location":"usage/enrichment/#automatic-enrichment","title":"Automatic enrichment","text":"<p>Enrichment can be conducted automatically in two distinct modes:</p> <ul> <li>Upon data arrival: Configuring the connector to run automatically when data arrives in OpenCTI ensures a real-time enrichment process, supplementing the platform's data. However, it's advisable to avoid automatic enrichment for quota-based connectors to paid sources to prevent quickly depleting all quotas. Additionally, this automatic enrichment contributes to increased data volume. On a large scale, with hundreds of thousands of objects, the disk space occupied by this data can be substantial, and it should be considered, especially if disk space is a concern. The automatic execution is configured at the connector level using the \"auto: true|false\" parameter.</li> <li>Targeted enrichment via playbooks: Enrichment can also be performed in a more targeted manner using playbooks. This approach allows for a customized enrichment strategy, focusing on specific objects and optimizing the relevance of the retrieved data.</li> </ul>"},{"location":"usage/enrichment/#manual-enrichment","title":"Manual enrichment","text":"<p>Manually initiating the enrichment process is straightforward. Simply locate the button with the cloud icon at the top right of an entity. </p> <p></p> <p>Clicking on this icon unveils a side panel displaying a list of available connectors that can be activated for the given object. If no connectors appear in the panel, it indicates that no enrichment connectors are available for the specific type of object in focus.</p> <p></p> <p>Activation of an enrichment connector triggers a contact with the designated remote source, importing a set of data into OpenCTI to enrich the selected object. Each enrichment connector operates uniquely, focusing on a specific set of object types it can enrich and a distinct set of data it imports. Depending on the connectors, they may, establish relationships, add external references, or complete object information, thereby contributing to the comprehensiveness of information within the platform.</p> <p>The list of available connectors can be found in our connectors catalog. In addition, further documentation on connectors is available on the dedicated documentation page.</p> <p>Impact of the max confidence level</p> <p>The maximum confidence level per user can have an impact on enrichment connectors, not being able to update data in the platform. To understand the concept and the potential issues you could face, please navigate to this page to understand.</p>"},{"location":"usage/exploring-analysis/","title":"Analyses","text":"<p>When you click on \"Analyses\" in the left-side bar, you see all the \"Analyses\" tabs, visible on the top bar on the left. By default, the user directly access the \"Reports\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Analyses</code> section, users can access the following tabs:</p> <ul> <li><code>Reports</code>: See Reports as a sort of containers to detail and structure what is contained on a specific report, either from a source or write by yourself. Think of it as an Intelligence Production in OpenCTI.</li> <li><code>Groupings</code>: Groupings are containers, like Reports, but do not represent an Intelligence Production. They regroup Objects sharing an explicit context. For example, a Grouping might represent a set of data that, in time, given sufficient analysis, would mature to convey an incident or threat report as Report container.</li> <li><code>Malware Analyses</code>: As define by STIX 2.1 standard, Malware Analyses captures the metadata and results of a particular static or dynamic analysis performed on a malware instance or family.</li> <li><code>Notes</code>: Through this tab, you can find all the Notes that have been written in the platform, for example to add some analyst's unstructured knowledge about an Object.</li> <li><code>External references</code>: Intelligence is never created from nothing. External references give user a way to link sources or reference documents to any Object in the platform.</li> </ul> <p></p>"},{"location":"usage/exploring-analysis/#reports","title":"Reports","text":""},{"location":"usage/exploring-analysis/#general-presentation","title":"General presentation","text":"<p>Reports are one of the central component of the platform. It is from a <code>Report</code> that knowledge is extracted and integrated in the platform for further navigation, analyses and exports. Always tying the information back to a report allows for the user to be able to identify the source of any piece of information in the platform at all time.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Report</code> is defined as such :</p> <p>Reports are collections of threat intelligence focused on one or more topics, such as a description of a threat actor, malware, or attack technique, including context and related details. They are used to group related threat intelligence together so that it can be published as a comprehensive cyber threat story.</p> <p>As a result, a <code>Report</code> object in OpenCTI is a set of attributes and metadata defining and describing a document outside the platform, which can be a threat intelligence report from a security reseearch team, a blog post, a press article a video, a conference extract, a MISP event, or any type of document and source.</p> <p>When clicking on the Reports tab at the top left, you see the list of all the Reports you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of reports.</p>"},{"location":"usage/exploring-analysis/#visualizing-knowledge-within-a-report","title":"Visualizing Knowledge within a Report","text":"<p>When clicking on a Report, you land on the Overview tab. For a Report, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge contained in the report, accessible through different views (See below for a dive-in). As described here.</li> <li>Content: a tab to upload or creates outcomes document displaying the content of the Report (for example in PDF, text, HTML or markdown files). The Content of the document is displayed to ease the access of Knowledge through a readable format. As described here.</li> <li>Entities: A table containing all SDO (Stix Domain Objects) contained in the Report, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables: A table containing all SCO (Stix Cyber Observable) contained in the Report, with search and filters available. It also displays if the SCO has been added directly or through inferences with the reasoning engine</li> <li>Data: as described here.</li> </ul> <p>Exploring and modifying the structured Knowledge contained in a Report can be done through different lenses.</p>"},{"location":"usage/exploring-analysis/#graph-view","title":"Graph View","text":"<p>In Graph view, STIX SDO are displayed as graph nodes and relationships as graph links. Nodes are colored depending of their type. Direct relationship are displayed as plain link and inferred relationships in dotted link. At the top right, you will find a serie of icons. From there you can change the current type of view. Here you can also perform global action on the Knowledge of the Report. Let's highlight 2 of them: - Suggestions: This tool suggests you some logical relationships to add between your contained Object to give more consistency to your Knowledge. - Share with an Organization: if you have designated a main Organization in the platform settings, you can here share your Report and its content with users of an other Organization. At the bottom, you have many option to manipulate the graph: - Multiple option for shaping the graph and applying forces to the nodes and links - Multiple selection options - Multiple filters, including a time range selector allowing you to see the evolution of the Knowledge within the Report. - Multiple creation and edition tools to modify the Knowledge contained in the Report.</p>"},{"location":"usage/exploring-analysis/#content-mapping-view","title":"Content mapping view","text":"<p>Through this view, you can map exsisting or new Objects directly from a readable content, allowing you to quickly append structured Knowledge in your Report before refining it with relationships and details.  This view is a great place to see the continuum between unstructured and structured Knowledge of a specific Intelligence Production.</p>"},{"location":"usage/exploring-analysis/#timeline-view","title":"Timeline view","text":"<p>This view allows you to see the structured Knowledge chronologically. This view is really useful when the report describes an attack or a campaign that lasted some time, and the analyst payed attention to the dates. The view can be filtered and displayed relationships too.</p>"},{"location":"usage/exploring-analysis/#correlation-view","title":"Correlation view","text":"<p>The correlation view is a great way to visualize and find other Reports related to your current subject of interest. This graph displays all Report related to the important nodes contained in your current Report, for example Objects like Malware or Intrusion sets.</p>"},{"location":"usage/exploring-analysis/#matrix-view","title":"Matrix view","text":"<p>If your Report describes let's say an attack, a campaign, or an understanding of an Intrusion set, it should contains multiple attack patterns Objects to structure the Knowledge about the TTPs of the Threat Actor. Those attack patterns can be displayed as highlighted matrices, by default the MITRE ATT&amp;CK Enterprise matrix. As some matrices can be huge, it can be also filtered to only display attack patterns describes in the Report.</p>"},{"location":"usage/exploring-analysis/#groupings","title":"Groupings","text":"<p>Groupings are an alternative to Report for grouping Objects sharing a context without describing an Intelligence Production.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Grouping</code> is defined as such :</p> <p>A Grouping object explicitly asserts that the referenced STIX Objects have a shared context, unlike a STIX Bundle (which explicitly conveys no context). A Grouping object should not be confused with an intelligence product, which should be conveyed via a STIX Report. A STIX Grouping object might represent a set of data that, in time, given sufficient analysis, would mature to convey an incident or threat report as a STIX Report object. For example, a Grouping could be used to characterize an ongoing investigation into a security event or incident. A Grouping object could also be used to assert that the referenced STIX Objects are related to an ongoing analysis process, such as when a threat analyst is collaborating with others in their trust community to examine a series of Campaigns and Indicators.</p> <p>When clicking on the Groupings tab at the top of the interface, you see the list of all the Groupings you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the groupings.</p> <p>Clicking on a Grouping, you land on its Overview tab. For a Groupings, the following tabs are accessible: - Overview: as described here. - Knowledge: a complex tab that regroups all the structured Knowledge contained in the groupings, as for a Report, except for the Timeline view. As described here. - Entities: A table containing all SDO (Stix Domain Objects) contained in the Grouping, with search and filters available. It also display if the SDO has been added directly or through inferences with the reasonging engine - Observables: A table containing all SCO (Stix Cyber Observable) contained in the Grouping, with search and filters available. It also display if the SDO has been added directly or through inferences with the reasonging engine - Data: as described here.</p>"},{"location":"usage/exploring-analysis/#malware-analyses","title":"Malware Analyses","text":"<p>Malware analyses are an important part of the Cyber Threat Intelligence, allowing an precise understanding of what and how a malware really do on the host but also how and from where it receives its command and communicates its results.</p> <p>In OpenCTI, Malware Analyses can be created from enrichment connectors that will take an Observable as input and perform a scan on a online service platform to bring back results. As such, Malware Analyses can be done on File, Domain and URL.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Malware Analyses</code> is defined as such :</p> <p>Malware Analyses captures the metadata and results of a particular static or dynamic analysis performed on a malware instance or family.</p> <p>When clicking on the Malware Analyses tab at the top of the interface, you see the list of all the Malware Analyses you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the Malware Analyses.</p> <p>Clicking on a Malware Analyses, you land on its Overview tab. The following tabs are accessible: - Overview: This view contains some additions from the common Overview here. You will find here details about how the analysis have been performed, what is the global result regarding the malicioussness of the analysed artifact and all the Observables that have been found during the analysis.  - Knowledge: If you Malware analysis is linked to other Objects that are not part of the analysis result, they will be displayed here. As described here. - Data: as described here. - History: as described here.</p> <p></p>"},{"location":"usage/exploring-analysis/#notes","title":"Notes","text":"<p>Not every Knowledge can be structured. For allowing any users to share their insights about a specific Knowledge, they can create a Note for every Object and relationship in OpenCTI they can access to. All the Notes are listed within the Analyses menu for allowing global review of this unstructured addition to the global Knowledge.</p> <p>In the MITRE STIX 2.1 documentation, a <code>Note</code> is defined as such :</p> <p>A Note is intended to convey informative text to provide further context and/or to provide additional analysis not contained in the STIX Objects, Marking Definition objects, or Language Content objects which the Note relates to. Notes can be created by anyone (not just the original object creator).</p> <p>Clicking on a Note, you land on its Overview tab. The following tabs are accessible: - Overview: as described here. - Data: as described here. - History: as described here.</p>"},{"location":"usage/exploring-analysis/#external-references","title":"External references","text":"<p>Intelligence is never created from nothing. External references give user a way to link sources or reference documents to any Object in the platform. All external references are listed within the Analyses menu for accessing directly sources of the structured Knowledge.</p> <p>In the MITRE STIX 2.1 documentation, a <code>External references</code> is defined as such :</p> <p>External references are used to describe pointers to information represented outside of STIX. For example, a Malware object could use an external reference to indicate an ID for that malware in an external database or a report could use references to represent source material.</p> <p>Clicking on an External reference, you land on its Overview tab. The following tabs are accessible: - Overview: as described here.</p>"},{"location":"usage/exploring-arsenal/","title":"Arsenal","text":"<p>When you click on \"Arsenal\" in the left-side bar, you access all the \"Arsenal\" tabs, visible on the top bar on the left. By default, the user directly access the \"Malware\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Arsenal</code> section, users can access the following tabs:</p> <ul> <li><code>Malware</code>: <code>Malware</code> represents any piece of code specifically designed to damage, disrupt, or gain unauthorized access to computer systems, networks, or user data.</li> <li><code>Channels</code>: <code>Channels</code>, in the context of cybersecurity, refer to places or means through which actors disseminate information. This category is used in particular in the context of FIMI (Foreign Information Manipulation Interference). </li> <li><code>Tools</code>: <code>Tools</code> represent legitimate, installed software or hardware applications on an operating system that can be misused by attackers for malicious purposes. (e.g. LOLBAS).</li> <li><code>Vulnerabilities</code>: <code>Vulnerabilities</code> are weaknesses or that can be exploited by attackers to compromise the security, integrity, or availability of a computer system or network.</li> </ul>"},{"location":"usage/exploring-arsenal/#malware","title":"Malware","text":""},{"location":"usage/exploring-arsenal/#general-presentation","title":"General presentation","text":"<p>Malware encompasses a broad category of malicious pieces of code built, deployed, and operated by intrusion set. Malware can take many forms, including viruses, worms, Trojans, ransomware, spyware, and more. These entities are created by individuals or groups, including state-nations, state-sponsored groups, corporations, or hacktivist collectives.</p> <p>Use the <code>Malware</code> SDO to model and track these threats comprehensively, facilitating in-depth analysis, response, and correlation with other security data.</p> <p>When clicking on the Malware tab on the top left, you see the list of all the Malware you have access to, in respect with your allowed marking definitions. These malware are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, related intrusion sets, countries and sectors they target, and labels. You can then search and filter on some common and specific attributes of Malware.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-a-malware","title":"Visualizing Knowledge associated with a Malware","text":"<p>When clicking on an <code>Malware</code> card you land on its Overview tab. For a Malware, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Malware. Different thematic views are proposed to easily see the victimology, the threat actors and intrusion sets using the Malware, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#channels","title":"Channels","text":""},{"location":"usage/exploring-arsenal/#general-presentation_1","title":"General presentation","text":"<p><code>Channels</code> - such as forums, websites and social media platforms (e.g. Twitter, Telegram) - are mediums for disseminating news, knowledge, and messages to a broad audience. While they offer benefits like open communication and outreach, they can also be leveraged for nefarious purposes, such as spreading misinformation, coordinating cyberattacks, or promoting illegal activities. </p> <p>Monitoring and managing content within <code>Channels</code> aids in analyzing threats, activities, and indicators associated with various threat actors, campaigns, and intrusion sets.</p> <p>When clicking on the Channels tab at the top left, you see the list of all the Channels you have access to, in respect with your allowed marking definitions. These channels are displayed in a list where you can find certain fields characterizing the entity: type of channel, labels, and dates. You can then search and filter on some common and specific attributes of Channels.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-a-channel","title":"Visualizing Knowledge associated with a Channel","text":"<p>When clicking on a <code>Channel</code> in the list, you land on its Overview tab. For a Channel, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Channel. Different thematic views are proposed to easily see the victimology, the threat actors and intrusion sets using the Malware, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#tools","title":"Tools","text":""},{"location":"usage/exploring-arsenal/#general-presentation_2","title":"General presentation","text":"<p><code>Tools</code> refers to legitimate, pre-installed software applications, command-line utilities, or scripts that are present on a compromised system. These objects enable you to model and monitor the activities of these tools, which can be misused by attackers.</p> <p>When clicking on the <code>Tools</code> tab at the top left, you see the list of all the <code>Tools</code> you have access to, in respect with your allowed marking definitions. These tools are displayed in a list where you can find certain fields characterizing the entity: labels and dates. You can then search and filter on some common and specific attributes of Tools.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-an-observed-data","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on a <code>Tool</code> in the list, you land on its Overview tab. For a Tool, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Tool. Different thematic views are proposed to easily see the threat actors, the intrusion sets and the malware using the Tool. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-arsenal/#vulnerabilities","title":"Vulnerabilities","text":""},{"location":"usage/exploring-arsenal/#general-presentation_3","title":"General presentation","text":"<p><code>Vulnerabilities</code> represent weaknesses or flaws in software, hardware, configurations, or systems that can be exploited by malicious actors. This object assists in managing and tracking the organization's security posture by identifying areas that require attention and remediation, while also providing insights into associated intrusion sets, malware and campaigns where relevant.</p> <p>When clicking on the <code>Vulnerabilities</code> tab at the top left, you see the list of all the <code>Vulnerabilities</code> you have access to, in respect with your allowed marking definitions. These vulnerabilities are displayed in a list where you can find certain fields characterizing the entity: CVSS3 severity, labels, dates and creators (in the platform). You can then search and filter on some common and specific attributes of Vulnerabilities.</p> <p></p>"},{"location":"usage/exploring-arsenal/#visualizing-knowledge-associated-with-an-observed-data_1","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on a <code>Vulnerabilities</code> in the list, you land on its Overview tab. For a Vulnerability, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Vulnerability. Different thematic views are proposed to easily see the threat actors, the intrusion sets and the malware exploiting the Vulnerability. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-cases/","title":"Cases","text":"<p>When you click on \"Cases\" in the left-side bar, you access all the \"Cases\" tabs, visible on the top bar on the left. By default, the user directly access the \"Incident Responses\" tab, but can navigate to the other tabs as well.</p> <p>As Analyses, <code>Cases</code> can contain other objects. This way, by adding context and results of your investigations in the case, you will be able to get an up-to-date overview of the ongoing situation, and later produce more easily an incident report. </p> <p>From the <code>Cases</code> section, users can access the following tabs:</p> <ul> <li><code>Incident Responses</code>: This type of Cases is dedicated to the management of incidents. An Incident Response case does not represent an incident, but all the context and actions that will encompass the response to a specific incident.</li> <li><code>Request for Information</code>: CTI teams are often asked to provide extensive information and analysis on a specific subject, be it related to an ongoing incident or a particular trending threat. Request for Information cases allow you to store context and actions relative to this type of request and its response.</li> <li><code>Request for Takedown</code>: When an organization is targeted by an attack campaign, a typical response action can be to request the Takedown of elements of the attack infrastructure, for example a domain name impersonating the organization to phish its employees, or an email address used to deliver phishing content. As Takedown needs in most case to reach out to external providers and be effective quickly, it often needs specific workflows. Request for Takedown cases give you a dedicated space to manage these specific actions.</li> <li><code>Tasks</code>: In every case, you need tasks to be performed in order to solve it. The Tasks tab allows you to review all created tasks to quickly see past due date, or quickly see every task assigned to a specific user.</li> <li><code>Feedbacks</code>: If you use your platform to interact with other teams and provide them CTI Knowledge, some users may want to give you feedback about it. Those feedbacks can easily be considered as another type of case to solve, as it will often refer to Knowledge inconsistency or gaps.</li> </ul> <p></p>"},{"location":"usage/exploring-cases/#incident-response-request-for-information-request-for-takedown","title":"Incident Response, Request for Information &amp; Request for Takedown","text":""},{"location":"usage/exploring-cases/#general-presentation","title":"General presentation","text":"<p>Incident responses, Request for Information &amp; Request for Takedown cases are an important part of the case management system in OpenCTI. Here, you can organize the work of your team to respond to cybersecurity situations. You can also give context to the team and other users on the platform about the situation and actions (to be) taken.</p> <p>To manage the situation, you can issue <code>Tasks</code> and assign them to users in the platform, by directly creating a Task or by applying a Case template that will append a list of predefined tasks.</p> <p>To bring context, you can use your Case as a container (like Reports or Groupings), allowing you to add any Knowledge from your platform in it. You can also use this possibility to trace your investigation, your Case playing the role of an Incident report. You will find more information about case management here.</p> <p>Incident Response, Request for Information &amp; Request for Takedown are not STIX 2.1 Objects.</p> <p>When clicking on the Incident Response, Request for Information &amp; Request for Takedown tabs at the top, you see the list of all the Cases you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes.</p>"},{"location":"usage/exploring-cases/#visualizing-knowledge-within-an-incident-response-request-for-information-request-for-takedown","title":"Visualizing Knowledge within an Incident Response, Request for Information &amp; Request for Takedown","text":"<p>When clicking on an Incident Response, Request for Information or Request for Takedown, you land on the Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: Overview of Cases are slightly different from the usual (described here). Cases' Overview displays also the list of the tasks associated with the case. It also let you highlight Incident, Report or Sighting at the origin of the case. If other cases contains some Observables with your Case, they will be displayed as Related Cases in the Overview.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge contained in the Case, accessible through different views (See below for a dive-in). As described here.</li> <li>Content: a tab to upload or creates outcomes document displaying the content of the Case (for example in PDF, text, HTML or markdown files). The Content of the document is displayed to ease the access of Knowledge through a readable format. As described here.</li> <li>Entities: A table containing all SDO (Stix Domain Objects) contained in the Case, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables: A table containing all SCO (Stix Cyber Observable) contained in the Case, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Data: as described here.</li> </ul> <p>Exploring and modifying the structured Knowledge contained in a Case can be done through different lenses.</p>"},{"location":"usage/exploring-cases/#graph-view","title":"Graph View","text":"<p>In Graph view, STIX SDO are displayed as graph nodes and relationships as graph links. Nodes are colored depending on their type. Direct relationship are displayed as plain link and inferred relationships in dotted link. At the top right, you will find a series of icons. From there you can change the current type of view. Here you can also perform global action on the Knowledge of the Case. Let's highlight 2 of them:</p> <ul> <li>Suggestions: This tool suggests you some logical relationships to add between your contained Object to give more consistency to your Knowledge.</li> <li>Share with an Organization: if you have designated a main Organization in the platform settings, you can here share your Case and its content with users of another Organization. At the bottom, you have many option to manipulate the graph:</li> <li>Multiple option for shaping the graph and applying forces to the nodes and links</li> <li>Multiple selection options</li> <li>Multiple filters, including a time range selector allowing you to see the evolution of the Knowledge within the Case.</li> <li>Multiple creation and edition tools to modify the Knowledge contained in the Case.</li> </ul>"},{"location":"usage/exploring-cases/#content-mapping-view","title":"Content mapping view","text":"<p>Through this view, you can map existing or new Objects directly from a readable content, allowing you to quickly append structured Knowledge in your Case before refining it with relationships and details. This view is a great place to see the continuum between unstructured and structured Knowledge.</p>"},{"location":"usage/exploring-cases/#timeline-view","title":"Timeline view","text":"<p>This view allows you to see the structured Knowledge chronologically. This view is particularly useful in the context of a Case, allowing you to see the chain of events, either from the attack perspectives, the defense perspectives or both. The view can be filtered and displayed relationships too.</p>"},{"location":"usage/exploring-cases/#matrix-view","title":"Matrix view","text":"<p>If your Case contains attack patterns, you will be able to visualize them in a Matrix view.</p>"},{"location":"usage/exploring-cases/#tasks","title":"Tasks","text":"<p>Tasks are actions to be performed in the context of a Case (Incident Response, Request for Information, Request for Takedown). Usually, a task is assigned to a user, but important tasks may involve more participants.</p> <p>When clicking on the Tasks tab at the top of the interface, you see the list of all the Tasks you have access to, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of the tasks.</p> <p>Clicking on a Task, you land on its Overview tab. For a Tasks, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-cases/#feedbacks","title":"Feedbacks","text":"<p>When a user fill a feedback form from its Profile/Feedback menu, it will then be accessible here.</p> <p>This feature gives the opportunity to engage with other users of your platform and to respond directly to their concern about it or the Knowledge, without the need of third party software.</p> <p></p> <p>Clicking on a Feedback, you land on its Overview tab. For a Feedback, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Content: as described here. </li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-entities/","title":"Entities","text":"<p>OpenCTI's Entities objects provides a comprehensive framework for modeling various targets and attack victims within your threat intelligence data. With five distinct Entity object types, you can represent sectors, events, organizations, systems, and individuals. This robust classification empowers you to contextualize threats effectively, enhancing the depth and precision of your analysis.</p> <p>When you click on \"Entities\" in the left-side bar, you access all the \"Entities\" tabs, visible on the top bar on the left. By default, the user directly access the \"Sectors\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Entities</code> section, users can access the following tabs:</p> <ul> <li><code>Sectors</code>: areas of activity.</li> <li><code>Events</code>: event in the real world.</li> <li><code>Organizations</code>: groups with specific aims such as companies and government entities.</li> <li><code>Systems</code>: technologies such as platforms and software.</li> <li><code>Individuals</code>: real persons.</li> </ul>"},{"location":"usage/exploring-entities/#sectors","title":"Sectors","text":""},{"location":"usage/exploring-entities/#general-presentation","title":"General presentation","text":"<p>Sectors represent specific domains of activity, defining areas such as energy, government, health, finance, and more. Utilize sectors to categorize targeted industries or sectors of interest, providing valuable context for threat intelligence analysis within distinct areas of the economy.</p> <p>When clicking on the Sectors tab at the top left, you see the list of all the Sectors you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-a-sector","title":"Visualizing Knowledge associated with a Sector","text":"<p>When clicking on a <code>Sector</code> in the list, you land on its Overview tab. For a Sector, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Sector. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Sector. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Sector.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-entities/#events","title":"Events","text":""},{"location":"usage/exploring-entities/#general-presentation_1","title":"General presentation","text":"<p>Events encompass occurrences like international sports events, summits (e.g., G20), trials, conferences, or any significant happening in the real world. By modeling events, you can analyze threats associated with specific occurrences, allowing for targeted investigations surrounding high-profile incidents.</p> <p>When clicking on the Events tab at the top left, you see the list of all the Events you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-event","title":"Visualizing Knowledge associated with an Event","text":"<p>When clicking on an <code>Event</code> in the list, you land on its Overview tab. For an Event, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Event. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Event. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted during an attack against the Event.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-entities/#organizations","title":"Organizations","text":""},{"location":"usage/exploring-entities/#general-presentation_2","title":"General presentation","text":"<p>Organizations include diverse entities such as companies, government bodies, associations, non-profits, and other groups with specific aims. Modeling organizations enables you to understand the threat landscape concerning various entities, facilitating investigations into cyber-espionage, data breaches, or other malicious activities targeting specific groups.</p> <p>When clicking on the Organizations tab at the top left, you see the list of all the Organizations you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-organization","title":"Visualizing Knowledge associated with an Organization","text":"<p>When clicking on an <code>Organization</code> in the list, you land on its Overview tab. For an Organization, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Organization. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Organization. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Organization.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, an Organization can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the Organization (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the Organization is the author.</li> </ul> <p></p>"},{"location":"usage/exploring-entities/#systems","title":"Systems","text":""},{"location":"usage/exploring-entities/#general-presentation_3","title":"General presentation","text":"<p>Systems represent software applications, platforms, frameworks, or specific tools like WordPress, VirtualBox, Firefox, Python, etc. Modeling systems allows you to focus on threats related to specific software or technology, aiding in vulnerability assessments, patch management, and securing critical applications.</p> <p>When clicking on the Systems tab at the top left, you see the list of all the Systems you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-a-system","title":"Visualizing Knowledge associated with a System","text":"<p>When clicking on a <code>System</code> in the list, you land on its Overview tab. For a System, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the System. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the System. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the System.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, a System can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the System (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the System is the author.</li> </ul>"},{"location":"usage/exploring-entities/#individuals","title":"Individuals","text":""},{"location":"usage/exploring-entities/#general-presentation_4","title":"General presentation","text":"<p>Individuals represent specific persons relevant to your threat intelligence analysis. This category includes targeted individuals, or influential figures in various fields. Modeling individuals enables you to analyze threats related to specific people, enhancing investigations into cyber-stalking, impersonation, or other targeted attacks.</p> <p>When clicking on the Individuals tab at the top left, you see the list of all the Individuals you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-entities/#visualizing-knowledge-associated-with-an-individual","title":"Visualizing Knowledge associated with an Individual","text":"<p>When clicking on an <code>Individual</code> in the list, you land on its Overview tab. For an Individual, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Individual. Different thematic views are proposed to easily see the related entities, the threats, the locations, etc. linked to the Individual. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in the Individual.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p>Furthermore, an Individual can be observed from an \"Author\" perspective. It is possible to change this viewpoint to the right of the entity name, using the \"Display as\" drop-down menu (see screenshot below). This different perspective is accessible in the Overview, Knowledge and Analyses tabs. When switched to \"Author\" mode, the observed data pertains to the entity's description as an author within the platform:</p> <ul> <li>Overview: The \"Latest created relationships\" and \"Latest containers about the object\" panels are replaced by the \"Latest containers authored by this entity\" panel.</li> <li>Knowledge: A tab that presents an overview of the data authored by the Individual (i.e. counters and a graph).</li> <li>Analyses: The list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) for which the Individual is the author.</li> </ul>"},{"location":"usage/exploring-events/","title":"Events","text":"<p>When you click on \"Events\" in the left-side bar, you access all the \"Events\" tabs, visible on the top bar on the left. By default, the user directly access the \"Incidents\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Events</code> section, users can access the following tabs:</p> <ul> <li><code>Incidents</code>: In OpenCTI, <code>Incidents</code> correspond to a negative event happening on an information system. This can include a cyberattack (intrusion, phishing, etc.), a consolidated security alert generated by a SIEM or EDR that need to be qualified, and so on. It can also refer to an information warfare attack in the context of countering disinformation.</li> <li><code>Sightings</code>: <code>Sightings</code> correspond to the event in which an <code>Observable</code> (IP, domain name, certificate, etc.) is detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or an EDR.</li> <li><code>Observed Data</code>: <code>Observed Data</code> has been added in OpenCTI by compliance with the STIX 2.1 standard. You can see it has a pseudo-container that contains Observables, like a line of firewall log for example. Currently, it is rarely used.</li> </ul>"},{"location":"usage/exploring-events/#incidents","title":"Incidents","text":""},{"location":"usage/exploring-events/#general-presentation","title":"General presentation","text":"<p>Incidents usually represents negative events impacting resources you want to protect, but local definitions can vary a lot, from a simple security events send by a SIEM to a massive scale supply chain attack impacting a whole activity sector.</p> <p>In the MITRE STIX 2.1, the <code>Incident</code> SDO has not yet been finalized and is the object of important work as part of a forthcoming STIX Extension.</p> <p>When clicking on the Incidents tab at the top left, you see the list of all the Incidents you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-an-incident","title":"Visualizing Knowledge associated with an Incident","text":"<p>When clicking on an <code>Incident</code> in the list, you land on its Overview tab. For an Incident, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display two distribution graphs of its related Entities (STIX SDO) and Observable (STIX SCO).</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Incident. Different thematic views are proposed to easily see the victimology, arsenal, techniques and so on used in the context of the Incident. As described here.</li> <li>Content: This specific tab allows to previzualize, manage and write deliverable associated with the Incident. For example an analytic report to share with other teams, a markdown files to feed a collaborative wiki with, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-events/#sightings","title":"Sightings","text":""},{"location":"usage/exploring-events/#general-presentation_1","title":"General presentation","text":"<p>The <code>Sightings</code> correspond to events in which an <code>Observable</code> (IP, domain name, url, etc.) is detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or EDR. </p> <p>In OpenCTI, as we are in a cybersecurity context, <code>Sightings</code> are associated with <code>Indicators</code> of Compromise (IoC) and the notion of \"True positive\" and \"False positive\". </p> <p>It is important to note that Sightings are a type of relationship (not a STIX SDO or STIX SCO), between an Observable and an Entities or Locations.</p> <p>When clicking on the Sightings tab at the top left, you see the list of all the Sightings you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-a-sighting","title":"Visualizing Knowledge associated with a Sighting","text":"<p>When clicking on a <code>Sighting</code> in the list, you land on its Overview tab. As other relationships in the platform, Sighting's overview displays common related metadata, containers, external references, notes and entities linked by the relationship. </p> <p>In addition, this overview displays: - Qualification : if the Sighting is a True Positive or a False Positive - Count : number of times the event has been seen</p>"},{"location":"usage/exploring-events/#observed-data","title":"Observed Data","text":""},{"location":"usage/exploring-events/#general-presentation_2","title":"General presentation","text":"<p><code>Observed Data</code> correspond to an extract from a log that contains Observables. </p> <p>In the MITRE STIX 2.1, the <code>Observed Data</code> SDO is defined as such:</p> <p>Observed Data conveys information about cybersecurity related entities such as files, systems, and networks using the STIX Cyber-observable Objects (SCOs). For example, Observed Data can capture information about an IP address, a network connection, a file, or a registry key. Observed Data is not an intelligence assertion, it is simply the raw information without any context for what it means.</p> <p>When clicking on the <code>Observed Data</code> tab at the top left, you see the list of all the <code>Observed Data</code> you have access to, in respect with your allowed marking definitions.</p>"},{"location":"usage/exploring-events/#visualizing-knowledge-associated-with-an-observed-data","title":"Visualizing Knowledge associated with an Observed Data","text":"<p>When clicking on an <code>Observed Data</code> in the list, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display a distribution graphs of its related Observables (STIX SCO).</li> <li>Entities : a sortable and filterable list of all Entities (SDO) </li> <li>Observables: a sortable and filterable list of all Observables (SCO) in relation with the Observed Data</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/","title":"Location","text":"<p>OpenCTI's Locations objects provides a comprehensive framework for representing various geographic entities within your threat intelligence data. With five distinct Location object types, you can precisely define regions, countries, areas, cities, and specific positions. This robust classification empowers you to contextualize threats geographically, enhancing the depth and accuracy of your analysis.</p> <p>When you click on \"Locations\" in the left-side bar, you access all the \"Locations\" tabs, visible on the top bar on the left. By default, the user directly access the \"Regions\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Locations</code> section, users can access the following tabs:</p> <ul> <li><code>Regions</code>: very large geographical territories, such as a continent.</li> <li><code>Countries</code>: the world's countries.</li> <li><code>Areas</code>: more or less extensive geographical areas and often not having a very defined limit</li> <li><code>Cities</code>: the world's cities.</li> <li><code>Positions</code>: very precise positions on the globe.</li> </ul>"},{"location":"usage/exploring-locations/#regions","title":"Regions","text":""},{"location":"usage/exploring-locations/#general-presentation","title":"General presentation","text":"<p>Regions encapsulate broader geographical territories, often representing continents or significant parts of continents. Examples include EMEA (Europe, Middle East, and Africa), Asia, Western Europe, and North America. Utilize regions to categorize large geopolitical areas and gain macro-level insights into threat patterns.</p> <p>When clicking on the Regions tab at the top left, you see the list of all the Regions you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-region","title":"Visualizing Knowledge associated with a Region","text":"<p>When clicking on a <code>Region</code> in the list, you land on its Overview tab. For a Region, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Region.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Region. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Region. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a Region.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-locations/#countries","title":"Countries","text":""},{"location":"usage/exploring-locations/#general-presentation_1","title":"General presentation","text":"<p>Countries represent individual nations across the world. With this object type, you can specify detailed information about a particular country, enabling precise localization of threat intelligence data. Countries are fundamental entities in geopolitical analysis, offering a focused view of activities within national borders.</p> <p>When clicking on the Countries tab at the top left, you see the list of all the Countries you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-country","title":"Visualizing Knowledge associated with a Country","text":"<p>When clicking on a <code>Country</code> in the list, you land on its Overview tab. For a Country, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Country.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Country. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Country. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a Country.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#areas","title":"Areas","text":""},{"location":"usage/exploring-locations/#general-presentation_2","title":"General presentation","text":"<p>Areas define specific geographical regions of interest, such as the Persian Gulf, the Balkans, or the Caucasus. Use areas to identify unique zones with distinct geopolitical, cultural, or strategic significance. This object type facilitates nuanced analysis of threats within defined geographic contexts.</p> <p>When clicking on the Areas tab at the top left, you see the list of all the Areas you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-an-area","title":"Visualizing Knowledge associated with an Area","text":"<p>When clicking on an <code>Area</code> in the list, you land on its Overview tab. For an Area, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the Area.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Area. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Area. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in an Area.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#cities","title":"Cities","text":""},{"location":"usage/exploring-locations/#general-presentation_3","title":"General presentation","text":"<p>Cities provide granular information about urban centers worldwide. From major metropolises to smaller towns, cities are crucial in understanding localized threat activities. With this object type, you can pinpoint threats at the urban level, aiding in tactical threat assessments and response planning.</p> <p>When clicking on the Cities tab at the top left, you see the list of all the Cities you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-city","title":"Visualizing Knowledge associated with a City","text":"<p>When clicking on a <code>City</code> in the list, you land on its Overview tab. For a City, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity of not having a <code>Details</code> section but a map locating the City.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the City. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the City. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted in a City.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-locations/#positions","title":"Positions","text":""},{"location":"usage/exploring-locations/#general-presentation_4","title":"General presentation","text":"<p>Positions represent highly precise geographical points, such as monuments, buildings, or specific event locations. This object type allows you to define exact coordinates, enabling accurate mapping of events or incidents. Positions enhance the granularity of your threat intelligence data, facilitating precise geospatial analysis.</p> <p>When clicking on the Positions tab at the top left, you see the list of all the Positions you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-locations/#visualizing-knowledge-associated-with-a-position","title":"Visualizing Knowledge associated with a Position","text":"<p>When clicking on a <code>Position</code> in the list, you land on its Overview tab. For a Position, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display a map locating the Position.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Position. Different thematic views are proposed to easily see the related entities, the threats, the incidents, etc. linked to the Position. As described here.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which an <code>Indicator</code> (IP, domain name, url, etc.) is sighted at a Position.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-observations/","title":"Observations","text":"<p>When you click on \"Observations\" in the left-side bar, you access all the \"Observations\" tabs, visible on the top bar on the left. By default, the user directly access the \"Observables\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Observations</code> section, users can access the following tabs:</p> <ul> <li><code>Observables</code>: An <code>Observable</code> represents an immutable object. Observables can encompass a wide range of entities such as IPv4 addresses, domain names, email addresses, and more.</li> <li><code>Artefacts</code>: In OpenCTI, the <code>Artefacts</code> is a particular Observable. It may contain a file, such as a malware sample.</li> <li><code>Indicators</code>: An <code>Indicator</code> is a detection object. It is defined by a search pattern, which could be expressed in various formats such as STIX, Sigma, YARA, among others.</li> <li><code>Infrastructures</code>: An <code>Infrastructure</code> describes any systems, software services and any associated physical or virtual resources intended to support some purpose (e.g. C2 servers used as part of an attack, devices or servers that are part of defense, database servers targeted by an attack, etc.).</li> </ul>"},{"location":"usage/exploring-observations/#observables","title":"Observables","text":""},{"location":"usage/exploring-observations/#general-presentation","title":"General presentation","text":"<p>An Observable is a distinct entity from the Indicator within OpenCTI and represents an immutable object. Observables can encompass a wide range of entities such as IPv4 addresses, domain names, email addresses, and more. Importantly, Observables don't inherently imply malicious intent, they can include items like legitimate IP addresses or domains associated with an organization. Additionally, they serve as raw data points without the additional detection context found in Indicators.</p> <p>When clicking on the Observables tab at the top left, you see the list of all the Observables you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-observable","title":"Visualizing Knowledge associated with an Observable","text":"<p>When clicking on an <code>Observable</code> in the list, you land on its Overview tab. For an Observable, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display Indicators composed with the Observable.</li> <li>Knowledge: a tab listing all its relationships and nested objects.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Observable</code> (IP, domain name, url, etc.) has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#artefacts","title":"Artefacts","text":""},{"location":"usage/exploring-observations/#general-presentation_1","title":"General presentation","text":"<p>An Artefact is a particular Observable. It may contain a file, such as a malware sample. Files can be uploaded or downloaded in encrypted archives, providing an additional layer of security against potential manipulation of malicious payloads.</p> <p>When clicking on the Artefacts tab at the top left, you see the list of all the Artefacts you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-artefact","title":"Visualizing Knowledge associated with an Artefact","text":"<p>When clicking on an <code>Artefact</code> in the list, you land on its Overview tab. For an Artefact, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to be able to download the attached file.</li> <li>Knowledge: a tab listing all its relationships and nested objects.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Artefact</code> has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#indicators","title":"Indicators","text":""},{"location":"usage/exploring-observations/#general-presentation_2","title":"General presentation","text":"<p>An Indicator is a detection object. It is defined by a search pattern, which could be expressed in various formats such as STIX, Sigma, YARA, among others. This pattern serves as a key to identify potential threats within the data. Furthermore, an Indicator includes additional information that enriches its detection context. This information encompasses:</p> <ul> <li>Validity dates: Indicators are accompanied by a time frame, specifying the duration of their relevance, and modeled by the <code>Valid from</code> and <code>Valid until</code> dates.</li> <li>Actionable fields: Linked to the validity dates, the <code>Revoked</code> and <code>Detection</code> fields can be used to sort Indicators for detection purposes.</li> <li>Kill chain phase: They indicate the phase within the cyber kill chain where they are applicable, offering insights into the progression of a potential threat.</li> <li>Types: Indicators are categorized based on their nature, aiding in classification and analysis.</li> </ul> <p>When clicking on the Indicators tab at the top left, you see the list of all the Indicators you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-indicator","title":"Visualizing Knowledge associated with an Indicator","text":"<p>When clicking on an <code>Indicator</code> in the list, you land on its Overview tab. For an Indicator, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display the Observables on which it is based.</li> <li>Knowledge: a tab listing all its relationships.</li> <li>Analyses: as described here.</li> <li>Sightings: a table containing all <code>Sightings</code> relationships corresponding to events in which the <code>Indicator</code> has been sighted.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul> <p></p>"},{"location":"usage/exploring-observations/#infrastructures","title":"Infrastructures","text":""},{"location":"usage/exploring-observations/#general-presentation_3","title":"General presentation","text":"<p>An Infrastructure refers to a set of resources, tools, systems, or services employed by a threat to conduct their activities. It represents the underlying framework or support system that facilitates malicious operations, such as the command and control (C2) servers in an attack. Notably, like Observables, an Infrastructure doesn't inherently imply malicious intent. It can also represent legitimate resources affiliated with an organization (e.g. devices or servers that are part of defense, database servers targeted by an attack, etc.).</p> <p>When clicking on the Infrastructures tab at the top left, you see the list of all the Infrastructures you have access to, in respect with your allowed marking definitions.</p> <p></p>"},{"location":"usage/exploring-observations/#visualizing-knowledge-associated-with-an-infrastructure","title":"Visualizing Knowledge associated with an Infrastructure","text":"<p>When clicking on an <code>Infrastructure</code> in the list, you land on its Overview tab. For an Infrastructure, the following tabs are accessible:</p> <ul> <li>Overview: as described here, with the particularity to display distribution graphs of its related Observable (STIX SCO).</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Infrastructure. Different thematic views are proposed to easily see the threats, the arsenal, the observations, etc. linked to the Infrastructure. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/","title":"Techniques","text":"<p>When you click on \"Techniques\" in the left-side bar, you access all the \"Techniques\" tabs, visible on the top bar on the left. By default, the user directly access the \"Attack pattern\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Techniques</code> section, users can access the following tabs:</p> <ul> <li><code>Attack pattern</code>: attacks pattern used by the threat actors to perform their attacks. By default, OpenCTI is provisionned with attack patterns from MITRE ATT&amp;CK matrices (for CTI) and DISARM matrix (for FIMI).</li> <li><code>Narratives</code>: In OpenCTI, narratives used by threat actors can be represented and linked to other Objects. Narratives are mainly used in the context of disinformation campaigns where it is important to trace which narratives have been and are still used by threat actors.</li> <li><code>Courses of action</code>: A Course of Action is an action taken either to prevent an attack or to respond to an attack that is in progress. It may describe technical, automatable responses (applying patches, reconfiguring firewalls) but can also describe higher level actions like employee training or policy changes. For example, a course of action to mitigate a vulnerability could describe applying the patch that fixes it.</li> <li><code>Data sources</code>: Data sources represent the various subjects/topics of information that can be collected by sensors/logs. Data sources also include data components, </li> <li><code>Data components</code>: Data components identify specific properties/values of a data source relevant to detecting a given ATT&amp;CK technique or sub-technique.</li> </ul>"},{"location":"usage/exploring-techniques/#attack-pattern","title":"Attack pattern","text":""},{"location":"usage/exploring-techniques/#general-presentation","title":"General presentation","text":"<p>Attacks pattern used by the threat actors to perform their attacks. By default, OpenCTI is provisionned with attack patterns from MITRE ATT&amp;CK matrices and CAPEC (for CTI) and DISARM matrix (for FIMI).</p> <p>In the MITRE STIX 2.1 documentation, an <code>Attack pattern</code> is defined as such :</p> <p>Attack Patterns are a type of TTP that describe ways that adversaries attempt to compromise targets. Attack Patterns are used to help categorize attacks, generalize specific attacks to the patterns that they follow, and provide detailed information about how attacks are performed. An example of an attack pattern is \"spear phishing\": a common type of attack where an attacker sends a carefully crafted e-mail message to a party with the intent of getting them to click a link or open an attachment to deliver malware. Attack Patterns can also be more specific; spear phishing as practiced by a particular threat actor (e.g., they might generally say that the target won a contest) can also be an Attack Pattern.</p> <p>When clicking on the Attack pattern tab at the top left, you access the list of all the attack pattern you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of attack patterns.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-an-attack-pattern","title":"Visualizing Knowledge associated with an Attack pattern","text":"<p>When clicking on an Attack pattern, you land on its Overview tab. For an Attack pattern, the following tabs are accessible:</p> <ul> <li> <p>Overview: Overview of Attack pattern is a bit different as the usual described here. The \"Details\" box is more structured and contains information about:</p> </li> <li> <p>parent or subtechniques (as in the MITRE ATT&amp;CK matrices), </p> </li> <li>related kill chain phases</li> <li>Platform on which the Attack pattern is usable,</li> <li>permission required to apply it</li> <li>Related detection technique</li> <li>Courses of action to mitigate the Attack pattern</li> <li>Data components in which find data to detect the usage of the Attack pattern</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Attack pattern. Different thematic views are proposed to easily see Threat Actors and Intrusion Sets using this techniques, linked incidents, etc.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#narratives","title":"Narratives","text":""},{"location":"usage/exploring-techniques/#general-presentation_1","title":"General presentation","text":"<p>In OpenCTI, narratives used by threat actors can be represented and linked to other Objects. Narratives are mainly used in the context of disinformation campaigns where it is important to trace which narratives have been and are still used by threat actors.</p> <p>An example of Narrative can be \"The country A is weak and corrupted\" or \"The ongoing operation aims to free people\". </p> <p>Narrative can be a mean in the context of a more broad attack or the goal of the operation, a vision to impose.</p> <p>When clicking on the Narrative tab at the top left, you access the list of all the Narratives you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of narratives.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-narrative","title":"Visualizing Knowledge associated with a Narrative","text":"<p>When clicking on a Narrative, you land on its Overview tab. For a Narrative, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Narratives. Different thematic views are proposed to easily see the Threat actors and Intrusion Set using the Narrative, etc. </li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#courses-of-action","title":"Courses of action","text":""},{"location":"usage/exploring-techniques/#general-presentation_2","title":"General presentation","text":"<p>In the MITRE STIX 2.1 documentation, an <code>Course of action</code> is defined as such :</p> <p>A Course of Action is an action taken either to prevent an attack or to respond to an attack that is in progress. It may describe technical, automatable responses (applying patches, reconfiguring firewalls) but can also describe higher level actions like employee training or policy changes. For example, a course of action to mitigate a vulnerability could describe applying the patch that fixes it.</p> <p>When clicking on the <code>Courses of action</code> tab at the top left, you access the list of all the Courses of action you have access too, in respect with your allowed marking definitions. You can then search and filter on some common and specific attributes of course of action.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-course-of-action","title":"Visualizing Knowledge associated with a Course of action","text":"<p>When clicking on a <code>Course of Action</code>, you land on its Overview tab. For a Course of action, the following tabs are accessible:</p> <ul> <li>Overview: Overview of Course of action is a bit different as the usual described here. In \"Details\" box, mitigated attack pattern are listed.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Narratives. Different thematic views are proposed to easily see the Threat actors and Intrusion Set using the Narrative, etc. </li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-techniques/#data-sources-data-components","title":"Data sources &amp; Data components","text":""},{"location":"usage/exploring-techniques/#general-presentation_3","title":"General presentation","text":"<p>In the MITRE ATT&amp;CK documentation, <code>Data sources</code> are defined as such :</p> <p>Data sources represent the various subjects/topics of information that can be collected by sensors/logs. Data sources also include data components, which identify specific properties/values of a data source relevant to detecting a given ATT&amp;CK technique or sub-technique.</p>"},{"location":"usage/exploring-techniques/#visualizing-knowledge-associated-with-a-data-source-or-a-data-components","title":"Visualizing Knowledge associated with a Data source or a Data components","text":"<p>When clicking on a <code>Data source</code> or a <code>Data component</code>, you land on its Overview tab. For a Course of action, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/","title":"Threats","text":"<p>When you click on \"Threats\" in the left-side bar, you access all the \"Threats\" tabs, visible on the top bar on the left. By default, the user directly access the \"Threat Actor (Group)\" tab, but can navigate to the other tabs as well.</p> <p>From the <code>Threats</code> section, users can access the following tabs:</p> <ul> <li><code>Threat actors (Group)</code>: Threat actor (Group) represents a physical group of attackers operating an Intrusion set, using malware and attack infrastructure, etc.</li> <li><code>Threat actors (Indvidual)</code>: Threat actor (Individual) represents a real attacker that can be described by physical and personal attributes and motivations. Threat actor (Individual) operates Intrusion set, uses malware and infrastructure, etc.</li> <li><code>Intrusion sets</code>: Intrusion set is an important concept in Cyber Threat Intelligence field. It is a consistent set of technical and non-technical elements corresponding of what, how and why a Threat actor acts. it is particularly useful for associating multiple attacks and malicious actions to a defined Threat, even without sufficient information regarding who did them. Often, with you understanding of the threat growing, you will link an Intrusion set to a Threat actor (either a Group or an Individual).</li> <li><code>Campaigns</code>: Campaign represents a series of attacks taking place in a certain period of time and/or targeting a consistent subset of Organization/Individual.</li> </ul>"},{"location":"usage/exploring-threats/#threat-actors-group-and-individual","title":"Threat actors (Group and Individual)","text":""},{"location":"usage/exploring-threats/#general-presentation","title":"General presentation","text":"<p>Threat actors are the humans who are building, deploying and operating intrusion sets. A threat actor can be an single individual or a group of attackers (who may be composed of individuals). A group of attackers may be a state-nation, a state-sponsored group, a corporation, a group of hacktivists, etc. </p> <p>Beware, groups of attackers might be modelled as \"Intrusion sets\" in feeds, as there is sometimes a misunderstanding in the industry between group of people and the technical/operational intrusion set they operate.</p> <p></p> <p>When clicking on the Threat actor (Group or Individual) tabs at the top left, you see the list of all the groups of Threat actors or Individual Threat actors you have access to, in respect with your allowed marking definitions. These groups or individual are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware they used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Threat actors.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#demographic-and-biographic-information","title":"Demographic and Biographic Information","text":"<p>Individual Threat actors have unique properties to represent demographic and biographic information. Currently tracked demographics include their countries of residence, citizenships, date of birth, gender, and more.</p> <p></p> <p>Biographic information includes their eye and hair color, as well as known heights and weights.</p> <p></p> <p>An Individual Threat actor can also be tracked as employed by an Organization or a Threat Actor group. This relationship can be set under the knowledge tab.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-a-threat-actor","title":"Visualizing Knowledge associated with a Threat actor","text":"<p>When clicking on a Threat actor Card, you land on its Overview tab. For a Threat actor, the following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Threat actor. Different thematic views are proposed to easily see the victimology, arsenal and techniques used by the Threat actor, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/#intrusion-sets","title":"Intrusion Sets","text":"<p>An intrusion set is a consistent group of technical elements such as \"tactics, technics and procedures\" (TTP), tools, malware and infrastructure used by a threat actor against one or a number of victims who are usually sharing some characteristics (field of activity, country or region) to reach a similar goal whoever the victim is. The intrusion set may be deployed once or several times and may evolve with time. Several intrusion sets may be linked to one threat actor. All the entities described below may be linked to one intrusion set. There are many debates in the Threat Intelligence community on how to define an intrusion set and how to distinguish several intrusion sets with regards to:</p> <ul> <li>their differences</li> <li>their evolutions</li> <li>the possible reuse</li> <li>\"false flag\" type of attacks</li> </ul> <p>As OpenCTI is very customizable, each organization or individual may use these categories as they wish. Instead, it is also possible to use the import feed for the choice of categories.</p> <p></p> <p>When clicking on the Intrusion set tab on the top left, you see the list of all the Intrusion sets you have access to, in respect with your allowed marking definitions. These intrusion sets are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware they used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Intrusion set.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-an-intrusion-set","title":"Visualizing Knowledge associated with an Intrusion set","text":"<p>When clicking on an Intrusion set Card, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Intrusion Set. Different thematic views are proposed to easily see the victimology, arsenal and techniques used by the Intrusion Set, etc. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/exploring-threats/#campaigns","title":"Campaigns","text":"<p>A campaign can be defined as \"a series of malicious activities or attacks (sometimes called a \"wave of attacks\") taking place within a limited period of time, against a defined group of victims, associated to a similar intrusion set and characterized by the use of one or several identical malware towards the various victims and common TTPs\". However, a campaign is an investigation element and may not be widely recognized. Thus, a provider might define a series of attacks as a campaign and another as an intrusion set. Campaigns can be attributed to an Intrusion set.</p> <p></p> <p>When clicking on the Campaign tab on the top left, you see the list of all the Campaigns you have access to, in respect with your allowed marking definitions. These campaigns are displayed as Cards where you can find a summary of the important Knowledge associated with each of them: description, aliases, malware used, countries and industries they target, labels. You can then search and filter on some common and specific attributes of Campaigns.</p> <p>At the top right of each Card, you can click the star icon to put it as favorite. It will pin the card on top of the list. You will also be able to display all your favorite easily in your Custom Dashboards.</p>"},{"location":"usage/exploring-threats/#visualizing-knowledge-associated-with-a-campaign","title":"Visualizing Knowledge associated with a Campaign","text":"<p>When clicking on an Campaign Card, you land on its Overview tab. The following tabs are accessible:</p> <ul> <li>Overview: as described here.</li> <li>Knowledge: a complex tab that regroups all the structured Knowledge linked to the Campaign. Different thematic views are proposed to easily see the victimology, arsenal and techniques used in the context of the Campaign. As described here.</li> <li>Analyses: as described here.</li> <li>Data: as described here.</li> <li>History: as described here.</li> </ul>"},{"location":"usage/export/","title":"Manual export","text":""},{"location":"usage/export/#introduction","title":"Introduction","text":"<p>With the OpenCTI platform, you can manually export your intelligence content in the following formats:</p> <ul> <li>JSON,</li> <li>CSV,</li> <li>PDF,</li> <li>TXT.</li> </ul> <p></p>"},{"location":"usage/export/#export-in-structured-or-document-format","title":"Export in structured or document format","text":""},{"location":"usage/export/#generate-an-export","title":"Generate an export","text":"<p>To export one or more entities you have two possibilities. First you can click on the button \"Open export panel\". The list of pre-existing exports will open, and in the bottom right-hand corner you can configure and generate a new export.</p> <p> This opens the export settings panel, where you can customize your export according to four fields:</p> <ul> <li>desired export format (text/csv, application/pdf, application/vnd.oasis.stix+json, text/plain)</li> <li>export type (simple or full),</li> <li>the max marking definition levels of the elements to be included in the export (a TLP level, for instance). 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.</li> <li>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.```</li> </ul> <p></p> <p>The second way is to click directly on the \"Generate an Export\" button to export the content of an entity in the desired format. The same settings panel will open.</p> <p></p> <p>Both ways add your export in the Exported files list in the Data tab. </p>"},{"location":"usage/export/#export-possibilities","title":"Export possibilities","text":"<p>All entities in your instance can be exported either directly via Generate Export or indirectly via Export List in .json and .csv formats.</p>"},{"location":"usage/export/#export-a-list-entities","title":"Export a list entities","text":"<p>You have the option to export either a single element, such as a report, or a collection of elements, such as multiple reports. These exports may contain not only the entity itself but also related elements, depending on the type of export you select: \"simple\" or \"full\". See the Export types (simple and full) section.</p> <p>You can also choose to export a list of entities within a container. To do so, go to the container's entities tab. For example, for a report, if you only want to retrieve entity type attack pattern and indicators to design a detection strategy, go to the entities tab and select specific elements for export.</p> <p></p> <p></p>"},{"location":"usage/export/#export-types-simple-and-full","title":"Export types (simple and full)","text":"<p>When you wish to export only the content of a specific entity such as a report, you can choose a \"simple\" export type.</p> <p>If you also wish to export associated content, you can choose a \"full\" export. With this type of export, the entity will be exported along with all entities directly associated with the central one (first neighbors).</p> <p></p>"},{"location":"usage/export/#exports-list-panel","title":"Exports list panel","text":"<p>Once an export has been created, you can find it in the export list panel. Simply click on a particular export to download it.</p> <p>You can also generate a new export directly from the Exports list, as explained in the Generate an export section.</p> <p></p>"},{"location":"usage/feeds/","title":"Native feeds","text":"<p>OpenCTI provides versatile mechanisms for sharing data through its built-in feeds, including Live streams, TAXII collections, and CSV feeds.</p>"},{"location":"usage/feeds/#feed-configuration","title":"Feed configuration","text":"<p>Feeds are configured in the \"Data &gt; Data sharing\" window. Configuration for all feed types is uniform and relies on the following parameters:</p> <ul> <li>Filter setup: The feed can have specific filters to publish only a subset of the platform overall knowledge. Any data that meets the criteria established by the user's feed filters will be shared (e.g. specific types of entities, labels, marking definitions, etc.).</li> <li>Access control: A feed can be either public, i.e. accessible without authentication, or restricted. By default, it's accessible to any user with the \"Access data sharing\" capability, but it's possible to increase restrictions by limiting access to a specific user, group, or organization.</li> </ul> <p></p> <p>By carefully configuring filters and access controls, you can tailor the behavior of Live streams, TAXII collections, and CSV feeds to align with your specific data-sharing needs.</p> <p></p>"},{"location":"usage/feeds/#live-streams","title":"Live streams","text":""},{"location":"usage/feeds/#introduction","title":"Introduction","text":"<p>Live streams, an exclusive OpenCTI feature, increase the capacity for real-time data sharing by serving STIX 2.1 bundles as TAXII collections with advanced capabilities. What distinguishes them is their dynamic nature, which includes the creation, updating, and deletion of data. Unlike TAXII, Live streams comprehensively resolve relationships and dependencies, ensuring a more nuanced and interconnected exchange of information. This is particularly beneficial in scenarios where sharing involves entities with complex relationships, providing a richer context for the shared data.</p> <p>In scenarios involving data sharing between two OpenCTI platforms, Live streams emerge as the preferred mechanism. These streams operate like TAXII collections but are notably enhanced, supporting:</p> <ul> <li>create, update and delete events depending on the parameters,</li> <li>caching already created entities in the last 5 minutes,</li> <li>resolving relationships and dependencies even out of the filters,</li> <li>can be public (without authentication).</li> </ul> <p></p> <p>Resolve relationships and dependencies</p> <p>Dependencies and relationships of entities shared via Live streams, as determined by specified filters, are automatically shared even beyond the confines of these filters. This means that interconnected data, which may not directly meet the filter criteria, is still included in the Live stream. However, OpenCTI data segregation mechanisms are still applied. They allow to restrict access to shared data based on factors such as markings or organization. It's imperative to carefully configure and manage these access controls to ensure that no confidential data is shared.</p>"},{"location":"usage/feeds/#illustrative-scenario","title":"Illustrative scenario","text":"<p>To better understand how live streams are working, let's take a few examples, from simple to complex.</p> <p>Given a live stream with filters Entity type: Indicator <code>AND</code> Label: detection. Let's see what happens with an indicator with:</p> <ul> <li>Marking definition: <code>TLP:GREEN</code></li> <li>Author <code>Crowdstrike</code></li> <li>Relation <code>indicates</code> to the malware <code>Emotet</code></li> </ul> Action Result in stream (with <code>Avoid dependencies resolution=true</code>) Result in stream (with <code>Avoid dependencies resolution=false</code>) 1. Create an indicator Nothing Nothing 2. Add the label <code>detection</code> Create <code>TLP:GREEN</code>, create <code>CrowdStrike</code>, create the indicator Create <code>TLP:GREEN</code>, create <code>CrowdStrike</code>, create the malware <code>Emotet</code>, create the indicator, create the relationship <code>indicates</code> 3. Remove the label <code>detection</code> Delete the indicator Delete the indicator and the relationship 4. Add the label <code>detection</code> Create the indicator Create the indicator, create the relationship <code>indicates</code> 5. Delete the indicator Delete the indicator Delete the indicator  and the relationship <p>Details on how to consume these Live streams can be found on the dedicated page.</p>"},{"location":"usage/feeds/#taxii-collections","title":"TAXII Collections","text":"<p>OpenCTI has an embedded TAXII API endpoint which provides valid STIX 2.1 bundles. If you wish to know more about the TAXII standard, please read the official introduction.</p> <p>In OpenCTI you can create as many TAXII 2.1 collections as needed. </p> <p></p> <p>After creating a new collection, every system with a proper access token can consume the collection using different kinds of authentication (basic, bearer, etc.). </p> <p>As when using the GraphQL API, TAXII 2.1 collections have a classic pagination system that should be handled by the consumer. Also, it's important to understand that element dependencies (nested IDs) inside the collection are not always contained/resolved in the bundle, so consistency needs to be handled at the client level.</p> <p></p>"},{"location":"usage/feeds/#csv-feeds","title":"CSV feeds","text":"<p>The CSV feed facilitates the automatic generation of a CSV file, accessible via a URL. The CSV file is regenerated and updated at user-defined intervals, providing flexibility. The entries in the file correspond to the information that matches the filters applied and that were created or modified in the platform during the time interval (between the last generation of the CSV and the new one).</p> <p></p> <p>CSV size limit</p> <p>The CSV file generated has a limit of 5 000 entries. If more than 5 000 entities are retrieved by the platform, only the most recent 5 000 will be shared in the file.</p>"},{"location":"usage/getting-started/","title":"Getting started","text":"<p>This guide aims to give you a full overview of the OpenCTI features and workflows. The platform can be used in various contexts to handle threats management use cases from a technical to a more strategic level. OpenCTI has been designed as a knowledge graph, taking inputs (threat intelligence feeds, sightings &amp; alerts, vulnerabilities, assets, artifacts, etc.) and generating outputs based on built-in capabilities and / or connectors.</p> <p>Here are some examples of use cases:</p> <ul> <li>Cyber Threat Intelligence knowledge base</li> <li>Detection as code feeds for XDR, EDR, SIEMs, firewalls, proxies, etc.</li> <li>Incident response artifacts &amp; cases management</li> <li>Vulnerabilities management</li> <li>Reporting, alerting and dashboarding on a subset of data</li> </ul> <p></p> <p></p>"},{"location":"usage/getting-started/#welcome-dashboard","title":"Welcome dashboard","text":"<p>The welcome page gives any visitor on the OpenCTI platform an overview of what's happening on the platform. It can be replaced by a custom dashboard, created by a user (or the default dashboard set up in a role, a group or an organization).</p> <p></p>"},{"location":"usage/getting-started/#indicators-in-the-dashboard","title":"Indicators in the dashboard","text":""},{"location":"usage/getting-started/#numbers","title":"Numbers","text":"Component Description Intrusion sets Number of intrusion sets       . Malware Number of malware. Reports Number of reports. Indicators Number of indicators."},{"location":"usage/getting-started/#charts-lists","title":"Charts &amp; lists","text":"Component Description Most active threats (3 last months) Top active threats (threat actor, intrusion set and campaign) during the last 3 months. Most targeted victims (3 last months) Intensity of the targeting tied to the number of relations <code>targets</code> for a given entities (organization, sector, location, etc.) during the last 3 months. Relationships created Volume of relationships created over the past 12 months. Most active malware (3 last months) Top active malware during the last 3 months. Most active vulnerabilities (3 last months) List of the vulnerabilities with the greatest number of relations over the last 3 months. Targeted countries (3 last months) Intensity of the targeting tied to the number of relations <code>targets</code> for a given country over the past 3 months. Latest reports Last reports ingested in the platform. Most active labels (3 last months) Top labels given to entities during the last 3 months. <p>Explore the platform</p> <p>To start exploring the platform and understand how information is structured, we recommend starting with the overview documentation page.</p>"},{"location":"usage/import-automated/","title":"Automated import","text":"<p>Automated imports in OpenCTI streamline the process of data ingestion, allowing users to effortlessly bring in valuable intelligence from diverse sources. This page focuses on the automated methods of importing data, which serve as bridges between OpenCTI and diverse external systems, formatting it into a STIX bundle, and importing it into the OpenCTI platform.</p>"},{"location":"usage/import-automated/#connectors","title":"Connectors","text":"<p>Connectors in OpenCTI serve as dynamic gateways, facilitating the import of data from a wide array of sources and systems. Every connector is designed to handle specific data types and structures of the source, allowing OpenCTI to efficiently ingest the data.</p>"},{"location":"usage/import-automated/#connector-behaviors","title":"Connector behaviors","text":"<p>The behavior of each connector is defined by its development, determining the types of data it imports and its configuration options. This flexibility allows users to customize the import process to their specific needs, ensuring a seamless and personalized data integration experience.</p> <p>The level of configuration granularity regarding the imported data type varies with each connector. Nevertheless, connectors empower users to specify the date from which they wish to fetch data. This capability is particularly useful during the initial activation of a connector, enabling the retrieval of historical data. Following this, the connector operates in real-time, continuously importing new data from the source.</p>"},{"location":"usage/import-automated/#connector-ecosystem","title":"Connector Ecosystem","text":"<p>OpenCTI's connector ecosystem covers a broad spectrum of sources, enhancing the platform's capability to integrate data from various contexts, from threat intelligence providers to specialized databases. The list of available connectors can be found in our connectors catalog. Connectors are categorized into three types: import connectors (the focus here), enrichment connectors, and stream consumers. Further documentation on connectors is available on the dedicated documentation page.</p> <p>In summary, automated imports through connectors empower OpenCTI users with a scalable, efficient, and customizable mechanism for data ingestion, ensuring that the platform remains enriched with the latest and most relevant intelligence.</p>"},{"location":"usage/import-automated/#native-automated-import","title":"Native automated import","text":"<p>In OpenCTI, the \"Data &gt; Ingestion\" section provides users with built-in functions for automated data import. These functions are designed for specific purposes and can be configured to seamlessly ingest data into the platform. Here, we'll explore the configuration process for the four built-in functions: Live Streams, TAXII Feeds, RSS Feeds, and CSV Feeds.</p>"},{"location":"usage/import-automated/#live-streams","title":"Live streams","text":"<p>Live Streams enable users to consume data from another OpenCTI platform, fostering collaborative intelligence sharing. Here's a step-by-step guide to configure Live streams synchroniser:</p> <ol> <li>Remote OpenCTI URL: Provide the URL of the remote OpenCTI platform (e.g., <code>https://[domain]</code>; don't include the path).</li> <li>Remote OpenCTI token: Provide the user token. An administrator from the remote platform must supply this token, and the associated user must have the \"Access data sharing\" privilege.</li> <li>After filling in the URL and user token, validate the configuration.</li> <li>Once validated, select a live stream to which you have access.</li> </ol> <p></p> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this stream. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Starting synchronization: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> <li>Take deletions into account: Enable this option to delete data from your platform if it was deleted on the providing stream. (Note: Data won't be deleted if another source has imported it previously.)</li> <li>Verify SSL certificate: Check the validity of the certificate of the domain hosting the remote platform.</li> <li>Avoid dependencies resolution: Import only entities without their relationships. For instance, if the stream shares malware, all the malware's relationships will be retrieved by default. This option enables you to choose not to recover them.</li> <li>Use perfect synchronization: This option is specifically for synchronizing two platforms. If an imported entity already exists on the platform, the one from the stream will overwrite it.</li> </ul> <p></p>"},{"location":"usage/import-automated/#taxii-feeds","title":"TAXII feeds","text":"<p>TAXII Feeds in OpenCTI provide a robust mechanism for ingesting TAXII collections from TAXII servers or other OpenCTI instances. Configuring TAXII ingester involves specifying essential details to seamlessly integrate threat intelligence data. Here's a step-by-step guide to configure TAXII ingesters:</p> <ol> <li>TAXII server URL: Provide the root API URL of the TAXII server. For collections from another OpenCTI instance, the URL is in the form <code>https://[domain]/taxii2/root</code>.</li> <li>TAXII collection: Enter the ID of the TAXII collection to be ingested. For collections from another OpenCTI instance, the ID follows the format <code>426e3acb-db50-4118-be7e-648fab67c16c</code>.</li> <li>Authentication type (if necessary): Enter the authentication type. For non-public collections from another OpenCTI instance, the authentication type is \"Bearer token.\" Enter the token of a user with access to the collection (similar to the point 2 of the Live streams configuration above).</li> </ol> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this TAXII feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> </ul> <p></p>"},{"location":"usage/import-automated/#rss-feeds","title":"RSS feeds","text":"<p>RSS Feeds functionality enables users to seamlessly ingest items in report form from specified RSS feeds. Configuring RSS Feeds involves providing essential details and selecting preferences to tailor the import process. Here's a step-by-step guide to configure RSS ingesters:</p> <ol> <li>RSS Feed URL: Provide the URL of the RSS feed from which items will be imported.</li> </ol> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this RSS feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> <li>Default report types: Indicate the report type to be applied to the imported report.</li> <li>Default author: Indicate the default author to be applied to the imported report. Please see the section \"Best practices\" below for more information.</li> <li>Default marking definitions: Indicate the default markings to be applied to the imported reports.</li> </ul> <p></p>"},{"location":"usage/import-automated/#csv-feeds","title":"CSV feeds","text":"<p>CSV feed ingester enables users to import CSV files exposed on URLs. Here's a step-by-step guide to configure TAXII ingesters:</p> <ol> <li>CSV URL: Provide the URL of the CSV file exposed from which items will be imported.</li> <li>CSV Mappers: Choose the CSV mapper to be used to import the data.</li> <li>Authentication type (if necessary): Enter the authentication type.</li> </ol> <p>CSV mapper</p> <p>CSV feed functionality is based on CSV mappers. It is necessary to create the appropriate CSV mapper to import the data contained in the file. See the page dedicated to the CSV mapper.</p> <p>Additional configuration options:</p> <ul> <li>User responsible for data creation: Define the user responsible for creating data received from this RSS feed. Best practice is to dedicate one user per source for organizational clarity. Please see the section \"Best practices\" below for more information.</li> <li>Import from date: Specify the date of the oldest data to retrieve. Leave the field empty to import everything.</li> </ul> <p></p> <p>To finalize the creation, click on \"Verify\" to run a check on the submitted URL with the selected CSV mapper. A valid URL-CSV mapper combination results in the identification of up to 50 entities.</p> <p></p> <p>To start your new ingester, click on \"Start\", in the burger menu.</p> <p></p> <p>CSV feed ingestion is made possible thanks to the connector \"ImportCSV\". So you can track the progress in \"Data &gt; Ingestion &gt; Connectors\". On a regular basis, the ingestion is updated when new data is added to the CSV feed.</p> <p></p> <p></p>"},{"location":"usage/import-automated/#best-practices-for-feed-import","title":"Best practices for feed import","text":"<p>Ensuring a secure and well-organized environment is paramount in OpenCTI. Here are two recommended best practices to enhance security, traceability, and overall organizational clarity:</p> <ol> <li>Create a dedicated user for each source: Generate a user specifically for feed import, following the convention <code>[F] Source name</code> for clear identification. Assign the user to the \"Connectors\" group to streamline user management and permission related to data creation. Please see here for more information on this good practice.</li> <li>Establish a dedicated Organization for the source: Create an organization named after the data source for clear identification. Assign the newly created organization to the \"Default author\" field in feed import configuration if available.</li> </ol> <p>By adhering to these best practices, you ensure independence in managing rights for each import source through dedicated user and organization structures. In addition, you enable clear traceability to the entity's creator, facilitating source evaluation, dashboard creation, data filtering and other administrative tasks.</p>"},{"location":"usage/import-automated/#digest","title":"Digest","text":"<p>Users can streamline the data ingestion process using various automated import capabilities. Each method proves beneficial in specific circumstances.</p> <ul> <li>Connectors act as bridges to retrieve data from diverse sources and format it for seamless ingestion into OpenCTI.</li> <li>Live Streams enable collaborative intelligence sharing across OpenCTI instances, fostering real-time updates and efficient data synchronization.</li> <li>TAXII Feeds provide a standardized mechanism for ingesting threat intelligence data from TAXII servers or other OpenCTI instances.</li> <li>RSS Feeds facilitate the import of items in report form from specified RSS feeds, offering a straightforward way to stay updated on relevant intelligence.</li> </ul> <p>By leveraging these automated import functionalities, OpenCTI users can build a comprehensive, up-to-date threat intelligence database. The platform's adaptability and user-friendly configuration options ensure that intelligence workflows remain agile, scalable, and tailored to the unique needs of each organization.</p>"},{"location":"usage/import-files/","title":"Import from files","text":""},{"location":"usage/import-files/#import-mechanisms","title":"Import mechanisms","text":"<p>The platform provides a seamless process for automatically parsing data from various file formats. This capability is facilitated by two distinct mechanisms.</p> <p>File import connectors: Currently, there are two connectors designed for importing files and automatically identifying entities.</p> <ul> <li><code>ImportFileStix</code>: Designed to handle STIX-structured files (json or xml format).</li> <li><code>ImportDocument</code>: Versatile connector supporting an array of file formats, including pdf, text, html, and markdown.</li> </ul> <p>CSV mappers: The CSV mapper is a tailored functionality to facilitate the import of data stored in CSV files. For more in-depth information on using CSV mappers, refer to the CSV Mappers documentation page.</p> <p></p>"},{"location":"usage/import-files/#usage","title":"Usage","text":""},{"location":"usage/import-files/#locations","title":"Locations","text":"<p>Both mechanisms can be employed wherever file uploads are possible. This includes the \"Data\" tabs of all entities and the dedicated panel named \"Data import and analyst workbenches\" located in the top right-hand corner (database logo with a small gear). Importing files from these two locations is not entirely equal; refer to the \"Relationship handling from entity's Data tab\" section below for details on this matter.</p>"},{"location":"usage/import-files/#entity-identification-process","title":"Entity identification process","text":"<p>For <code>ImportDocument</code> connector, the identification process involves searching for existing entities in the platform and scanning the document for relevant information. In additions, the connector use regular expressions (regex) to detect IP addresses and domains within the document.</p> <p>As for the <code>ImportFileStix</code> connector and the CSV mappers, there is no identification mechanism. The imported data will be, respectively, the data defined in the STIX bundle or according to the configuration of the CSV mapper used.</p>"},{"location":"usage/import-files/#workflow-overview","title":"Workflow overview","text":"<ol> <li>Upload file: Navigate to the desired location, such as the \"Data\" tabs of an entity or the \"Data import and analyst workbenches\" panel. Then, upload the file containing the relevant data by clicking on the small cloud with the arrow inside next to \"Uploaded files\".</li> <li>Entity identification: For a CSV file, select the connector and CSV mapper to be used by clicking on the icon with an upward arrow in a circle. If it's not a CSV file, the connector will launch automatically. Then, the file import connectors or CSV mappers will identify entities within the uploaded document.</li> <li>Workbench review and validation: Entities identified by connectors are not immediately integrated into the platform's knowledge base. Instead, they are thoughtfully placed in a workbench, awaiting review and validation by an analyst. Workbenches function as draft spaces, ensuring that no data is officially entered into the platform until the workbench has undergone the necessary validation process. For more information on workbenches, refer to the Analyst workbench documentation page.</li> </ol> <p>Review workbenches</p> <p>Import connectors may introduce errors in identifying object types or add \"unknown\" entities. Workbenches were established with the intent of reviewing the output of connectors before validation. Therefore, it is crucial to be vigilant when examining the workbench to prevent the import of incorrect data into the platform.</p> <p></p>"},{"location":"usage/import-files/#additional-information","title":"Additional information","text":""},{"location":"usage/import-files/#no-workbench-for-csv-mapper","title":"No workbench for CSV mapper","text":"<p>It's essential to note that CSV mappers operate differently from other import mechanisms. Unlike connectors, CSV mappers do not generate workbenches. Instead, the data identified by CSV mappers is imported directly into the platform without an intermediary workbench stage.</p>"},{"location":"usage/import-files/#relationship-handling-from-entitys-data-tab","title":"Relationship handling from entity's \"Data\" tab","text":"<p>When importing a document directly from an entity's \"Data\" tab, there can be an automatic addition of relationships between the objects identified by connectors and the entity in focus. The process differs depending on the type of entity in which the import occurs:</p> <ul> <li>If the entity is a container (e.g., Report, Grouping, and Cases), the identified objects in the imported file will be linked to the entity (upon workbench validation). In the context of a container, the object is said to be \"contained\".</li> <li>For entities that are not containers, a distinct behavior unfolds. In this scenario, the identified objects are not linked to the entity, except for Observables. <code>Related to</code> relationships between the Observables and the entity are automatically added to the workbench and created after validation of this one.</li> </ul>"},{"location":"usage/import-files/#file-import-in-content-tab","title":"File import in Content tab","text":"<p>Expanding the scope of file imports, users can seamlessly add files in the <code>Content</code> tab of Analyses or Cases. In this scenario, the file is directly added as an attachment without utilizing an import mechanism.</p>"},{"location":"usage/import-files/#user-capability-requirement","title":"User capability requirement","text":"<p>In order to initiate file imports, users must possess the requisite capability: \"Upload knowledge files.\" This capability ensures that only authorized users can contribute and manage knowledge files within the OpenCTI platform, maintaining a controlled and secure environment for data uploads.</p> <p>Deprecation warning</p> <p>Using the <code>ImportDocument</code> connector to parse CSV file is now disallowed as it produces inconsistent results. Please configure and use CSV mappers dedicated to your specific CSV content for a reliable parsing. CSV mappers can be created and configured in the administration interface.   </p>"},{"location":"usage/indicators-lifecycle/","title":"Indicators Lifecycle Management","text":""},{"location":"usage/indicators-lifecycle/#introduction","title":"Introduction","text":"<p>OpenCTI enforces strict rules to determine the period during which an indicator is effective for usage. This period is defined by the <code>valid_from</code> and <code>valid_until</code> dates. All along its lifecycle, the indicator <code>score</code> will decrease according to configured decay rules. After the indicator expires, the object is marked as <code>revoked</code> and the <code>detection</code> field is automatically set to <code>false</code>. Here, we outline how these dates are calculated within the OpenCTI platform and how the score is updated with decay rules.</p>"},{"location":"usage/indicators-lifecycle/#setting-validity-dates","title":"Setting validity dates","text":""},{"location":"usage/indicators-lifecycle/#data-source-provided-the-dates","title":"Data source provided the dates","text":"<p>If a data source provides <code>valid_from</code> and <code>valid_until</code> dates when creating an indicator on the platform, these dates are used without modification. But, if the creation is performed from the UI and the indicator is elligible to be manages by a decay rule, the platform will change this valid_until with the one calculated by the Decay rule.</p>"},{"location":"usage/indicators-lifecycle/#fallback-rules-for-unspecified-dates","title":"Fallback rules for unspecified dates","text":"<p>If a data source does not provide validity dates, OpenCTI applies the decay rule matching the indicator to determine these dates. The <code>valid_until</code> date is computed based on the revoke score of the decay rule : it is set at the exact time at which the indicator will reach the revoke score. Past <code>valid_until</code> date, the indicator is marked as revoked.</p>"},{"location":"usage/indicators-lifecycle/#score-decay","title":"Score decay","text":"<p>Indicators have an initial score at creation, either provided by data source, or 50 by default. Over time, this score is going to decrease according to the configured decay rules. Score is updated at each reaction point defined for the decay rule matching the indicator at creation.</p>"},{"location":"usage/indicators-lifecycle/#example","title":"Example","text":"<p>This URL indicator has matched the <code>Built-in IP and URL</code> decay rule. Its initial score at creation is 100. </p> <p></p> <p>Right next to the indicator score, there is a button <code>Lifecycle</code> which enables to open a dialog to see the details of the indicator's lifecyle.</p> <p></p>"},{"location":"usage/indicators-lifecycle/#conclusion","title":"Conclusion","text":"<p>Understanding how OpenCTI calculates validity periods and scores is essential for effective threat intelligence analysis. These rules ensure that your indicators are accurate and up-to-date, providing a reliable foundation for threat intelligence data.</p>"},{"location":"usage/inferences/","title":"Inferences and reasoning","text":""},{"location":"usage/inferences/#overview","title":"Overview","text":"<p>OpenCTI\u2019s inferences and reasoning capability is a robust engine that automates the process of relationship creation within your threat intelligence data. This capability, situated at the core of OpenCTI, allows logical rules to be applied to existing relationships, resulting in the automatic generation of new, pertinent connections.</p>"},{"location":"usage/inferences/#understanding-inferences-and-reasoning","title":"Understanding inferences and reasoning","text":"<p>Inferences and reasoning serve as OpenCTI\u2019s intelligent engine. It interprets your data logically. By activating specific predefined rules (of which there are around twenty), OpenCTI can deduce new relationships from the existing ones. For instance, if there's a connection indicating an Intrusion Set targets a specific country, and another relationship stating that this country is part of a larger region, OpenCTI can automatically infer that the Intrusion Set also targets the broader region.</p>"},{"location":"usage/inferences/#key-benefits","title":"Key benefits","text":"<ul> <li>Efficiency: Reduces manual workload by automating relationship creation, saving valuable analyst time.</li> <li>Completeness: Fills relationship gaps, ensuring a comprehensive and interconnected threat intelligence database.</li> <li>Accuracy: Minimizes manual input errors by deriving relationships from predefined, accurate logic.</li> </ul>"},{"location":"usage/inferences/#how-it-operates","title":"How it operates","text":"<p>When you activate an inference rule, OpenCTI continuously analyzes your existing relationships and applies the defined logical rules. These rules are logical statements that define conditions for new relationships. When the set of conditions is met, the OpenCTI creates the corresponding relationship automatically.</p> <p>For example, if you activate a rule as follows:</p> <p>IF [Entity A targets Identity B] AND [Identity B is part of Identity C] THEN [Entity A targets Identity C]</p> <p>OpenCTI will apply this rule to existing data. If it finds an Intrusion Set (\"Entity A\") targeting a specific country (\"Identity B\") and that country is part of a larger region (\"Identity C\"), the platform will automatically establish a relationship between the Intrusion Set and the region.</p>"},{"location":"usage/inferences/#identifying-inferred-relationships","title":"Identifying inferred relationships","text":"<p>In the knowledge graphs: Inferred relationships are represented by dotted lines of a different color, distinguishing them from non-inferred relations.</p> <p></p> <p>In the lists: In a relationship list, a magic wand icon at the end of the line indicates relationship created by inference.</p> <p></p>"},{"location":"usage/inferences/#additional-resources","title":"Additional resources","text":"<ul> <li>Administration: To find out about existing inference rules and enable/disable them, refer to the Rules engine page in the Administration section of the documentation.</li> <li>Playbooks: OpenCTI playbooks are highly customizable automation scenarios. This seamless integration allows for further automation, making your threat intelligence processes even more efficient and tailored to your specific needs. More information in our blog post</li> </ul>"},{"location":"usage/manual-creation/","title":"Manual creations","text":"<p>Manual data creation in OpenCTI is an intuitive process that occurs throughout the platform. This page provides guidance on two key aspects of manual creation: Entity creation and Relationship creation.</p>"},{"location":"usage/manual-creation/#entity-creation","title":"Entity creation","text":"<p>To create an entity:</p> <ol> <li>Navigate to the relevant section: Be on the section of the platform related to the object type you want to create.</li> <li>Click on the \"+\" icon: Locate the \"+\" icon located at the bottom right of the window. </li> <li>Fill in entity-specific fields: A form on the right side of the window will appear, allowing to fill in specific fields of the entity. Certain fields are inherently obligatory, and administrators have the option to designate additional mandatory fields (See here for more information). </li> <li>Click on \"Create\": Once you've filled in the desired fields, click on \"create\" to initiate the entity creation process.</li> </ol> <p></p>"},{"location":"usage/manual-creation/#relationship-creation","title":"Relationship creation","text":"<p>Before delving into the creation of relationships between objects in OpenCTI, it's crucial to grasp some foundational concepts. Here are key points to understand:</p> <ul> <li>On several aspects, including relationships, two categories of objects must be differentiated: containers (e.g., Reports, Groupings, and Cases) and others. Containers aren't related to but contains objects.</li> <li>Relationships, like all other entities, are objects. They possess fields, can be linked, and share characteristics identical to other entities.</li> <li>Relationships are inherently directional, comprising a \"from\" entity and a \"to\" entity. Understanding this directionality is essential for accurate relationship creation.</li> <li>OpenCTI supports various relationship types, and their usage depends on the entity types being linked. For example, a \"target\" relationship might link malware to an organization, while linking malware to an intrusion set might involve a different relationship type.</li> </ul> <p>Now, let\u2019s explore the process of creating relationships. To do this, we will differentiate the case of containers from the others. </p>"},{"location":"usage/manual-creation/#for-container","title":"For container","text":"<p>When it comes to creating relationships within containers in OpenCTI, the process is straightforward. Follow these steps to attach objects to a container:</p> <ol> <li>Navigate to the container: Go to the specific container to which you want to attach an object. This could be a Report, Grouping, or Cases.</li> <li>Access the \"Entities\" tab: Within the container, locate and access the \"Entities\" tab.</li> <li>Click on the \"+\" icon: Find the \"+\" icon located at the bottom right of the window. </li> <li>Search for entities: A side window will appear. Search for the entities you want to add to the container. </li> <li>Add entities to the container: Click on the desired entities. They will be added directly to the container.</li> </ol>"},{"location":"usage/manual-creation/#for-other","title":"For other","text":"<p>When creating relationships not involving a container, the creation method is distinct. Follow these steps to create relationships between entities:</p> <ol> <li>Navigate to one of the entities: Go to one of the entities you wish to link. Please be aware that the entity from which you create the relationship will be designated as the \"from\" entity for that relationship. So the decision of which entity to choose for creating the relationship should be considered, as it will impact the outcome. </li> <li>Access the \"Knowledge\" tab: Within the entity, go to the \"Knowledge\" tab.</li> <li>Select the relevant categories: In the right banner, navigate to the categories that correspond to the object to be linked. The available categories depend on the type of entity you are currently on. For example, if you are on malware and want to link to a sector, choose \"victimology.\"</li> <li>Click on the \"+\" icon: Find the \"+\" icon located at the bottom right of the window. </li> <li>Search for entities: A side window will appear. Search for the entities you want to link.</li> <li>Add entities and click on \"Continue\": Click on the entities you wish to link. Multiple entities can be selected. Then click on \"Continue\" at the bottom right. </li> <li>Fill in the relationship form: As relationships are objects, a creation form similar to creating an entity will appear. </li> <li>Click on \"Create\": Once you've filled in the desired fields, click on \"create\" to initiate the relationship creation process.</li> </ol> <p></p>"},{"location":"usage/manual-creation/#additional-methods","title":"Additional methods","text":"<p>While the aforementioned methods are primary for creating entities and relationships, OpenCTI offers versatility, allowing users to create objects in various locations within the platform. Here's a non-exhaustive list of additional places that facilitate on-the-fly creation:</p> <ul> <li>Creating entities during relationship creation: During the \"Search for entities\" phase (see above) of the relationship creation process, click on the \"+\" icon to create a new entity directly.</li> <li>Knowledge graph: Within the knowledge graph - found in the knowledge tab of the containers or in the investigation functionality - users can seamlessly create entities or relationships.</li> <li>Inside a workbench: The workbench serves as another interactive space where users can create entities and relationships efficiently.</li> </ul> <p>These supplementary methods offer users flexibility and convenience, allowing them to adapt their workflow to various contexts within the OpenCTI platform. As users explore the platform, they will naturally discover additional means of creating entities and relationships.</p> <p>Max confidence level</p> <p>When creating knowledge in the platform, the maximum confidence level of the users is used. Please navigate to this page to understand this concept and the impact it can have on the knowledge creation.</p>"},{"location":"usage/merging/","title":"Merge objects","text":""},{"location":"usage/merging/#introduction","title":"Introduction","text":"<p>OpenCTI\u2019s merge capability stands as a pivotal tool for optimizing threat intelligence data, allowing to consolidate multiple entities of the same type. This mechanism serves as a powerful cleanup tool, harmonizing the platform and unifying scattered information. In this section, we explore the significance of this feature, the process of merging entities, and the strategic considerations involved.</p> <p></p>"},{"location":"usage/merging/#data-streamlining","title":"Data streamlining","text":"<p>In the ever-expanding landscape of threat intelligence and the multitude of names chosen by different data sources, data cleanliness is essential. Duplicates and fragmented information hinder efficient analysis. The merge capability is a strategic solution for amalgamating related entities into a cohesive unit. Central to the merging process is the selection of a main entity. This primary entity becomes the anchor, retaining crucial attributes such as name and description. Other entities, while losing specific fields like descriptions, are aliased under the primary entity. This strategic decision preserves vital data while eliminating redundancy.</p>"},{"location":"usage/merging/#preserving-entity-relationships","title":"Preserving entity relationships","text":"<p>One of the key feature of the merge capability is its ability to preserve relationships. While merging entities, their interconnected relationships are not lost. Instead, they seamlessly integrate into the new, merged entity. This ensures that the intricate web of relationships within the data remains intact, fostering a comprehensive understanding of the threat landscape.</p>"},{"location":"usage/merging/#conclusion","title":"Conclusion","text":"<p>OpenCTI\u2019s merge capability helps improve the quality of threat intelligence data. By consolidating entities and centralizing relationships, OpenCTI empowers analysts to focus on insights and strategies, unburdened by data silos or fragmentation. However, exercising caution and foresight in the merging process is essential, ensuring a robust and streamlined knowledge basis.</p>"},{"location":"usage/merging/#additional-resources","title":"Additional resources","text":"<ul> <li>Administration: To understand how to merge entities and the consideration to take into account, refer to the Merging page in the Administration section of the documentation.</li> <li>Deduplication mechanism: the platform is equipped with deduplication processes that automatically merge data at creation (either manually or by importing data from different sources) if it meets certain conditions.</li> </ul>"},{"location":"usage/nested/","title":"Nested references and objects","text":""},{"location":"usage/nested/#stix-standard","title":"STIX standard","text":""},{"location":"usage/nested/#definition","title":"Definition","text":"<p>In the STIX 2.1 standard, objects can:</p> <ol> <li>Refer to other objects in directly in their <code>attributes</code>, by referencing one or multiple IDs.</li> <li>Have other objects directly embedded in the entity.</li> </ol>"},{"location":"usage/nested/#example","title":"Example","text":"<pre><code>{\n   \"type\": \"intrusion-set\",\n   \"spec_version\": \"2.1\",\n   \"id\": \"intrusion-set--4e78f46f-a023-4e5f-bc24-71b3ca22ec29\",\n   \"created_by_ref\": \"identity--f431f809-377b-45e0-aa1c-6a4751cae5ff\", // nested reference to an identity\n   \"object_marking_refs\": [\"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da\"], // nested reference to multiple marking defintions\n   \"external_references\": [\n      {\n         \"source_name\": \"veris\",\n         \"external_id\": \"0001AA7F-C601-424A-B2B8-BE6C9F5164E7\",\n         \"url\": \"https://github.com/vz-risk/VCDB/blob/125307638178efddd3ecfe2c267ea434667a4eea/data/json/validated/0001AA7F-C601-424A-B2B8-BE6C9F5164E7.json\",    \n      }\n   ],\n   \"created\": \"2016-04-06T20:03:48.000Z\",\n   \"modified\": \"2016-04-06T20:03:48.000Z\",\n   \"name\": \"Bobcat Breakin\",\n   \"description\": \"Incidents usually feature a shared TTP of a bobcat being released within the building containing network access...\",\n   \"aliases\": [\"Zookeeper\"],\n   \"goals\": [\"acquisition-theft\", \"harassment\", \"damage\"]\n}\n</code></pre> <p>In the previous example, we have 2 nested references to other objects in:</p> <pre><code>\"created_by_ref\": \"identity--f431f809-377b-45e0-aa1c-6a4751cae5ff\", // nested reference to an identity\n\"object_marking_refs\": [\"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da\"], // nested reference to multiple marking defintions\n</code></pre> <p>But we also have a nested object within the entity (an <code>External Reference</code>):</p> <pre><code>\"external_references\": [\n   {\n      \"source_name\": \"veris\",\n      \"external_id\": \"0001AA7F-C601-424A-B2B8-BE6C9F5164E7\",\n      \"url\": \"https://github.com/vz-risk/VCDB/blob/125307638178efddd3ecfe2c267ea434667a4eea/data/json/validated/0001AA7F-C601-424A-B2B8-BE6C9F5164E7.json\",    \n   }\n]\n</code></pre>"},{"location":"usage/nested/#implementation","title":"Implementation","text":""},{"location":"usage/nested/#modelization","title":"Modelization","text":"<p>In OpenCTI, all nested references and objects are modelized as relationships, to be able to pivot more easily on labels, external references, kill chain phases, marking definitions, etc.</p> <p></p>"},{"location":"usage/nested/#import-export","title":"Import &amp; export","text":"<p>When importing and exporting data to/from OpenCTI, the translation between nested references and objects to full-fledged nodes and edges is automated and therefore transparent for the users. Here is an example with the object in the graph above:</p> <pre><code>{\n   \"id\": \"file--b6be3f04-e50f-5220-af3a-86c2ca66b719\",\n   \"spec_version\": \"2.1\",\n   \"x_opencti_description\": \"...\",\n   \"x_opencti_score\": 50,\n   \"hashes\": {\n       \"MD5\": \"b502233b34256285140676109dcadde7\"\n   },\n   \"labels\": [\n       \"cookiecutter\",\n       \"clouddata-networks-1\"\n   ],\n   \"external_references\": [\n       {\n           \"source_name\": \"Sekoia.io\",\n           \"url\": \"https://app.sekoia.io/intelligence/objects/indicator--3e6d61b4-d5f0-48e0-b934-fdbe0d87ab0c\"\n       }\n   ],\n   \"x_opencti_id\": \"8a3d108f-908c-4833-8ff4-4d6fc996ce39\",\n   \"type\": \"file\",\n   \"created_by_ref\": \"identity--b5b8f9fc-d8bf-5f85-974e-66a7d6f8d4cb\",\n   \"object_marking_refs\": [\n       \"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9\"\n   ]\n}\n</code></pre>"},{"location":"usage/notifications/","title":"Notifications and alerting","text":"<p>In the evolving landscape of cybersecurity, timely awareness is crucial. OpenCTI empowers users to stay informed and act swiftly through its robust notifications and alerting system. This feature allows users to create personalized triggers that actively monitor the platform for specific events and notify them promptly when these conditions are met.</p> <p>From individual users tailoring their alert preferences to administrators orchestrating collaborative triggers for Groups or Organizations, OpenCTI's notification system is a versatile tool for keeping cybersecurity stakeholders in the loop.</p> <p>The main menu \"Notifications and triggers\" for creating and managing notifications is located in the top right-hand corner with the bell icon.</p> <p> </p>"},{"location":"usage/notifications/#triggers","title":"Triggers","text":"<p>In OpenCTI, triggers serve as personalized mechanisms for users to stay informed about specific events that align with their cybersecurity priorities. Users can create and manage triggers to tailor their notification experience. Each trigger operates by actively listening to events based on predefined filters and event types, promptly notifying users via chosen notifiers when conditions are met.</p> <p></p>"},{"location":"usage/notifications/#trigger-management","title":"Trigger management","text":"<p>Individual user triggers: Each user possesses the autonomy to craft their own triggers, finely tuned to their unique preferences and responsibilities. By setting up personalized filters and selecting preferred notifiers, users ensure that they receive timely and relevant notifications aligned with their specific focus areas.</p> <p>Administrative control: Platform administrators have the capability to create and manage triggers for Users, Groups and Organizations. This provides centralized control and the ability to configure triggers that address collective cybersecurity objectives. Users within the designated Group or Organization will benefit from triggers with read-only access rights. These triggers are to be created directly on the User|Group|Organization with whom to share them in \"Settings &gt; Security &gt; Users|Groups|Organizations\".</p> <p></p>"},{"location":"usage/notifications/#trigger-filters","title":"Trigger filters","text":"<p>Leveraging the filters, users can meticulously define the criteria that activate their triggers. This level of granularity ensures that triggers are accurate, responding precisely to events that matter most. Users can tailor filters to consider various parameters such as object types, markings, sources, or other contextual details. They can also allow notifications for the assignment of a Task, a Case, etc.</p> <p>Beyond filters, a trigger can be configured to respond to three event types: creation, modification, and deletion.</p> <p></p>"},{"location":"usage/notifications/#instance-triggers","title":"Instance triggers","text":"<p>Instance triggers offer a targeted approach to live monitoring by allowing users to set up triggers specific to one or several entities. These triggers, when activated, keep a vigilant eye on a predefined set of events related to the selected entities, ensuring that you stay instantly informed about crucial changes.</p>"},{"location":"usage/notifications/#creating-instance-triggers","title":"Creating instance triggers","text":"<p>Method 1: Using the general trigger creation form</p> <ol> <li>Go on the \"Notifications and triggers\" window.</li> <li>Navigate to the \"Triggers and digests\" tab.</li> <li>Access the general trigger creation form.</li> <li>Toggle the switch \"Instance trigger\".</li> <li>Choose the entities to monitor.</li> </ol> <p></p> <p>Method 2: Quick subscription</p> <ol> <li>On an entity's overview, locate the \"Instance trigger quick subscription\" button with the bell icon at the top right.</li> <li>Click on the button to create the instance trigger.</li> <li>(Optional) Click on it again to modify the instance trigger created.</li> </ol> <p></p>"},{"location":"usage/notifications/#events-monitored-by-instance-triggers","title":"Events monitored by instance triggers","text":"<p>An instance trigger set on an entity X actively monitors the following events:</p> <ul> <li>Update/Deletion of X: Stay informed when the selected entity undergoes changes or is deleted.</li> <li>Creation/Deletion of relationships: Receive notifications about relationships being added or removed from/to X.</li> <li>Creation/Deletion of related entities: Be alerted when entities that have X in its refs - i.e. contains X, is shared with X, is created by X, etc. - are created or deleted.</li> <li>Adding/Removing X in ref: Stay in the loop when X is included or excluded from the ref of other entities - i.e. adding X in the author of an entity, adding X in a report, etc.).</li> </ul> <p>Entity deletion notification</p> <p>It's important to note that the notification of entity deletion can occur in two scenarios:     - Real entity deletion: When the entity is genuinely deleted from the platform.     - Visibility loss: When a modification to the entity results in the user losing visibility for that entity.</p>"},{"location":"usage/notifications/#digest","title":"Digest","text":"<p>Digests provide an efficient way to streamline and organize your notifications. By grouping notifications based on selected triggers and specifying the delivery period (daily, weekly, monthly), you gain the flexibility to receive consolidated updates at your preferred time, as opposed to immediate notifications triggered by individual events.</p>"},{"location":"usage/notifications/#creating-digests","title":"Creating digests","text":"<ol> <li>Go on the \"Notifications and triggers\" window.</li> <li>Navigate to the \"Triggers and digests\" tab.</li> <li>Create a new digest.</li> <li>Configure digest: Set the parameters, including triggers to be included and the frequency of notifications (daily, weekly, monthly). </li> <li>Choose the notifier(s): Select the notification method(s) (e.g. within the OpenCTI interface, via email, etc.).</li> </ol>"},{"location":"usage/notifications/#benefits-of-digests","title":"Benefits of digests","text":"<ul> <li>Organized notifications: Digests enable you to organize and categorize notifications, preventing a flood of individual alerts.</li> <li>Customized delivery: Choose the frequency of digest delivery based on your preferences, whether it's a daily overview, a weekly summary, or a monthly roundup.</li> <li>Reduced distractions: Receive notifications at a scheduled time, minimizing interruptions and allowing you to focus on critical tasks.</li> </ul> <p>Digests enhance your control over notification management, ensuring a more structured and convenient approach to staying informed about important events.</p>"},{"location":"usage/notifications/#notifiers","title":"Notifiers","text":"<p>In OpenCTI, notifiers serve as the channels for delivering notifications, allowing users to stay informed about critical events. The platform offers two built-in notifiers, \"Default mailer\" for email notifications and \"User interface\" for in-platform alerts.</p> <p></p>"},{"location":"usage/notifications/#notifier-connectors","title":"Notifier connectors","text":"<p>OpenCTI features built-in notifier connectors that empower users to create personalized notifiers for notification and activity alerting. Three essential connectors are available:</p> <ul> <li>Platform mailer connector: Enables sending notifications directly within the OpenCTI platform.</li> <li>Simple mailer connector: Offers a straightforward approach to email notifications with simplified configuration options.</li> <li>Generic webhook connector: Facilitates communication through webhooks.</li> </ul> <p>OpenCTI provides two samples of webhook notifiers designed for Teams integration.</p> <p></p>"},{"location":"usage/notifications/#configuration-and-access","title":"Configuration and Access","text":"<p>Notifiers are manageable in the \"Settings &gt; Customization &gt; Notifiers\" window and can be restricted through Role-Based Access Control (RBAC). Administrators can restrict access to specific Users, Groups, or Organizations, ensuring controlled usage.</p> <p>For guidance on configuring custom notifiers and explore detailed setup instructions, refer to the dedicated documentation page.</p>"},{"location":"usage/overview/","title":"Overview","text":""},{"location":"usage/overview/#introduction","title":"Introduction","text":"<p>The following chapter aims at giving the reader a step-by-step description of what is available on the platform and the meaning of the different tabs and entries.</p> <p>When the user connects to the platform, the home page is the <code>Dashboard</code>. This <code>Dashboard</code> contains several visuals summarizing the types and quantity of data recently imported into the platform.</p> <p>Dashboard</p> <p>To get more information about the components of the default dashboard, you can consult the Getting started.</p> <p>The left side panel allows the user to navigate through different windows and access different views and categories of knowledge.</p> <p></p>"},{"location":"usage/overview/#structure","title":"Structure","text":""},{"location":"usage/overview/#the-hot-knowledge","title":"The \"hot knowledge\"","text":"<p>The first part of the platform in the left menu is dedicated to what we call the \"hot knowledge\", which means this is the entities and relationships which are added on a daily basis in the platform and which generally require work / analysis from the users.</p> <ul> <li><code>Analyses</code>: all containers which convey relevant knowledge such as reports, groupings and malware analyses.</li> <li><code>Cases</code>: all types of case like incident responses, requests for information, for takedown, etc.</li> <li><code>Events</code>: all incidents &amp; alerts coming from operational systems as well as sightings.</li> <li><code>Observations</code>: all technical data in the platform such as observables, artifacts and indicators.</li> </ul>"},{"location":"usage/overview/#the-cold-knowledge","title":"The \"cold knowledge\"","text":"<p>The second part of the platform in the left menu is dedicated to the \"cold knowledge\", which means this is the entities and relationships used in the hot knowledge. You can see this as the \"encyclopedia\" of all pieces of knowledge you need to get context: threats, countries, sectors, etc.</p> <ul> <li><code>Threats</code>: all threats entities from campaigns to threat actors, including intrusion sets.</li> <li><code>Arsenal</code>: all tools and pieces of malware used and/or targeted by threats, including vulnerabilities.</li> <li><code>Techniques</code>: all objects related to tactics and techniques used by threats (TTPs, etc.).</li> <li><code>Entities</code>: all non-geographical contextual information such as sectors, events, organizations, etc.</li> <li><code>Locations</code>: all geographical contextual information, from cities to regions, including precise positions.</li> </ul>"},{"location":"usage/overview/#hide-categories","title":"Hide categories","text":"<p>You can customize the experience in the platform by hiding some categories in the left menu, whether globally or for a specific role.</p>"},{"location":"usage/overview/#hide-categories-globally","title":"Hide categories globally","text":"<p>In the <code>Settings &gt; Parameters</code>, it is possible for the platform administrator to hide categories in the platform for all users.</p> <p></p>"},{"location":"usage/overview/#hide-categories-in-roles","title":"Hide categories in roles","text":"<p>In OpenCTI, the different roles are highly customizable. It is possible to defined default dashboards, triggers, etc. but also be able to hide categories in the roles:</p> <p></p>"},{"location":"usage/overview/#presentation-of-a-typical-page-in-opencti","title":"Presentation of a typical page in OpenCTI","text":"<p>While OpenCTI features numerous entities and tabs, many of them share similarities, with only minor differences arising from specific characteristics. These differences may involve the inclusion or exclusion of certain fields, depending on the nature of the entity.</p> <p>In this part will only be detailed a general outline of a \"typical\" OpenCTI page. The specifies of the different entities will be detailed in the corresponding pages below (Activities and Knowledge).</p> <p></p> <p></p>"},{"location":"usage/overview/#overview_1","title":"Overview","text":"<p>In the <code>Overview</code> tab on the entity, you will find all properties of the entity as well as the recent activities.</p> <p>First, you will find the <code>Details</code> section, where are displayed all properties specific to the type of entity you are looking at, an example below with a piece of malware:</p> <p></p> <p>Thus, in the <code>Basic information</code> section, are displayed all common properties to all objects in OpenCTI, such as the marking definition, the author, the labels (i.e. tags), etc.</p> <p></p> <p>Below these two sections, you will find latest modifications in the Knowledge base related to the Entity:</p> <ul> <li><code>Latest created relationships</code>: display the latest relationships that have been created from or to this Entity. For example, latest Indicators of Compromise and associated Threat Actor of a Malware.</li> <li><code>latest containers about the object</code>: display all the Cases and Analyses that contains this Entity. For example, the latest Reports about a Malware.</li> <li><code>External references</code>: display all the external sources associated with the Entity. You will often find here links to external reports or webpages from where Entity's information came from.</li> <li><code>History</code>: display the latest chronological modifications of the Entity and its relationships that occurred in the platform, in order to traceback any alteration.</li> </ul> <p> </p> <p>Last, all Notes written by users of the platform about this Entity are displayed in order to access unstructured analysis comments.</p> <p></p>"},{"location":"usage/overview/#knowledge","title":"Knowledge","text":"<p>In the <code>Knowledge</code> tab, which is the central part of the entity, you will find all the Knowledge related to the current entity. The <code>Knowledge</code> tab is different for Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) entities than for all the other entity types.</p> <ul> <li>The <code>Knowledge</code> tab of those entities (who represents Analyses or Cases that can contains a collection of Objects) is the place to integrate and link together entities. For more information on how to integrate information in OpenCTI using the knowledge tab of a report, please refer to the part Manual creation.</li> <li>The <code>Knowledge</code> tabs of any other entity (that does not aim to contain a collection of Objects) gather all the entities which have been at some point linked to the entity the user is looking at. For instance, as shown in the following capture, the <code>Knowledge</code> tab of Intrusion set APT29, gives access to the list of all entities APT29 is attributed to, all victims the intrusion set has targeted, all its campaigns, TTPs, malware etc. For entities to appear in these tabs under <code>Knowledge</code>, they need to have been linked to the entity directly or have been computed with the inference engine.</li> </ul> <p></p>"},{"location":"usage/overview/#focus-on-indicators-and-observables","title":"Focus on Indicators and Observables","text":"<p>The <code>Indicators</code> and <code>Observables</code> section offers 3 display modes: - The <code>entities view</code>, which displays the indicators/observables linked to the entity. - The <code>relationship view</code>, which displays the various relationships between the indicators/observables linked to the entity and the entity itself. - The <code>contextual view</code>, which displays the indicators/observables contained in the cases and analyses that contain the entity.</p> <p></p> <p></p>"},{"location":"usage/overview/#content","title":"Content","text":"<p>The <code>Content</code> tab allows for uploading and creating outcomes documents related to the content of the current entity (in PDF, text, HTML or markdown files). This specific tab enable to previzualize, manage and write deliverable associated with the entity. For example an analytic report to share with other teams, a markdown files to feed a collaborative wiki with, etc.</p> <p>The <code>Content</code> tab is available for a subset of entities: <code>Report</code>, <code>Incident</code>, <code>Incident response</code>, <code>Request for Information</code>, and <code>Request for Takedown</code>.</p> <p></p> <p></p>"},{"location":"usage/overview/#analyses","title":"Analyses","text":"<p>The <code>Analyses</code> tab contains the list of all Analyses (<code>Report</code>, <code>Groupings</code>) and Cases (<code>Incident response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>) in which the entity has been identified.</p> <p></p> <p>By default, this tab display the list, but you can also display the content of all the listed Analyses on a graph, allowing you to explore all their Knowledge and have a glance of the context around the Entity.</p> <p></p> <p></p>"},{"location":"usage/overview/#data","title":"Data","text":"<p>The <code>Data</code> tab contains documents that are associated to the object and were either:</p> <ul> <li>Uploaded to the platform : for instance the PDF document containing the text of the report</li> <li>Generated from the platform to be downloaded : a JSON or CSV file containing information on the object and generated by the user.</li> <li>associated to an external reference</li> </ul> <p>Analyst Workbench can also be created from here. They will contain the entity by default.</p> <p></p> <p>In addition, the <code>Data</code> tab of <code>Threat actors (group)</code>, <code>Threat actors (individual)</code>, <code>Intrusions sets</code>, <code>Organizations</code>, <code>Individuals</code> have an extra panel:</p> <ul> <li>Pictures Management: allows to manage the profile pictures attached to the entity.</li> </ul> <p> </p> <p></p>"},{"location":"usage/overview/#history","title":"History","text":"<p>The <code>History</code> tab displays the history of change of the Entity, update of attributes, creation of relations, ...</p> <p>Because of the volumes of information the history is written in a specific index that consume the redis stream to rebuild the history for the UI. </p>"},{"location":"usage/overview/#less-frequent-tabs","title":"Less frequent tabs","text":"<ul> <li>The <code>Observables</code> tab (for Reports and Observed data): A table containing all SCO (Stix Cyber Observable) contained in the Report or the Observed data, with search and filters available. It also displays if the SCO has been added directly or through inferences with the reasoning engine</li> <li>the <code>Entities</code> tab (for Reports and Observed data): A table containing all SDO (Stix Domain Objects) contained in the Report or the Observed data, with search and filters available. It also displays if the SDO has been added directly or through inferences with the reasoning engine</li> <li>Observables:</li> <li>the <code>Sightings</code> tab (for Indicators and Observables): A table containing all <code>Sightings</code> relationships corresponding to events in which <code>Indicators</code> (IP, domain name, URL, etc.) are detected by or within an information system, an individual or an organization. Most often, this corresponds to a security event transmitted by a SIEM or EDR.</li> </ul>"},{"location":"usage/pivoting/","title":"Pivot and investigate","text":"<p>In OpenCTI, all data are structured as an extensive knowledge graph, where every element is interconnected. The investigation functionality provides a powerful tool for pivoting on any entity or relationship within the platform. Pivoting enables users to explore and analyze connections between entities and relationships, facilitating a comprehensive understanding of the data.</p> <p>To access investigations, navigate to the top right corner of the toolbar:</p> <p></p> <p>Access restriction</p> <p>When an investigation is created, it is initially visible only to the creator, allowing them to work on the investigation before deciding to share it. The sharing mechanism is akin to that of dashboards. For further details, refer to the Access control section in the dashboard documentation page.</p>"},{"location":"usage/pivoting/#perform-investigation","title":"Perform investigation","text":""},{"location":"usage/pivoting/#manipulate-entity","title":"Manipulate entity","text":"<p>We can add any existing entity of the platform to your investigation.</p> <p></p> <p>After adding an entity, we can choose the entity and view its details in the panel that appears on the right of the screen.</p> <p>On each node, we'll notice a bullet with a number inside, serving as a visual indication of how many entities are linked to it but not currently displayed in the graph. Keep in mind that this number is an approximation, which is why there's a \"+\" next to it. If there's no bullet displayed, it means there's nothing to expand from this node.</p> <p></p>"},{"location":"usage/pivoting/#expansion","title":"Expansion","text":"<p>To incorporate these linked entities into the graph, we just have to expand the nodes. Utilize the button with a 4-arrows logo in the mentioned menu, or double-click on the entity directly. This action opens a new window where we can choose the types of entities and relationships we wish to expand.</p> <p></p> <p>For instance, in the image above, selecting the target Malware and the relationship Uses implies expanding in my investigation graph all Malware linked to this node with a relationship of type Uses.</p>"},{"location":"usage/pivoting/#roll-back-expansion","title":"Roll back expansion","text":"<p>Expanding a graph can add a lot of entities and relations, making it not only difficult to read but sometimes counterproductive since it brings entities and relations that are not useful to your investigations. To solve this problem, there is a button to undo the last expansion.</p> <p>When clicking on this button, we will retrieve the state in which your graph was before your expansion. As a result, please note that all add or remove actions made since the last expansion will be lost: in other words, if you have expanded your graph, and then have added some entities in your graph, when clicking on rollback button, the entities that you have added will not be in your graph.</p> <p></p> <p>You can roll back your investigation graph up to the last 10 expand actions.</p>"},{"location":"usage/pivoting/#manipulate-relationship","title":"Manipulate relationship","text":"<p>We can create a relationship between entities directly within our investigation. To achieve this, select multiple entities by clicking on them while holding down the shift key. Subsequently, a button appears at the bottom right to create one (or more, depending on the number of entities selected) relationships.</p> <p></p> <p>Relationship creation</p> <p>Creating a relationship in the investigation graph will generate the relationship in your knowledge base.</p>"},{"location":"usage/pivoting/#capitalize-on-an-investigation","title":"Capitalize on an investigation","text":""},{"location":"usage/pivoting/#export-investigation","title":"Export investigation","text":"<p>Users have the capability to export investigations, providing a way to share, document, or archive their findings.</p> <ul> <li>PDF and image formats: Users can export investigations in either PDF or image format, offering flexibility in sharing and documentation.</li> <li>STIX bundle: The platform allows the export of the entire content of an investigation graph as a STIX bundle. In the STIX format, all objects within the investigation graph are automatically aggregated into a Report object.</li> </ul> <p></p>"},{"location":"usage/pivoting/#turn-investigation-into-a-container","title":"Turn investigation into a container","text":"<p>Users can efficiently collect and consolidate the findings of an investigation by adding the content into dedicated containers. The contents of an investigation can be imported into various types of containers, including:</p> <ul> <li>Grouping</li> <li>Incident Response</li> <li>Report</li> <li>Request for Information</li> <li>Request for Takedown</li> </ul> <p></p> <p>We have the flexibility to choose between creating a new container on the fly or adding investigation content to an existing container. </p> <p></p> <p></p> <p>After clicking on the <code>ADD</code> button, the browser will redirect to the Knowledge tab of the container where we added the content of our investigation. If we added it to multiple containers, the redirection will be to the first of the list.</p> <p></p>"},{"location":"usage/reliability-confidence/","title":"Reliability and Confidence","text":""},{"location":"usage/reliability-confidence/#generalities","title":"Generalities","text":"<p>In (Cyber) Threat Intelligence, evaluation of information sources and of information quality is one of the most important aspect of the work. It is of the utter most importance to assess situations by taking into account reliability of the sources and credibility of the information.</p> <p>This concept is foundational in OpenCTI, and have real impact on:</p> <ul> <li>the data deduplication process</li> <li>the data stream filtering for ingestion and sharing</li> </ul>"},{"location":"usage/reliability-confidence/#what-is-the-reliability-of-a-source","title":"What is the Reliability of a source?","text":"<p>Reliability of a source of information is a measurement of the trust that the analyst can have about the source, based on the technical capabilities or history of the source. Is the source a reliable partner with long sharing history? A competitor? Unknown?</p> <p>Reliability of sources are often stated at organizational level, as it requires an overview of the whole history with it. </p> <p>In the Intelligence field, Reliability is often notated with the NATO Admiralty code.</p>"},{"location":"usage/reliability-confidence/#what-is-confidence-of-an-information","title":"What is Confidence of an information?","text":"<p>Reliability of a source is important but even a trusted source can be wrong. Information in itself has a credibility, based on what is known about the subject and the level of corroboration by other sources.</p> <p>Credibility is often stated at the analyst team level, expert of the subject, able to judge the information with its context.</p> <p>In the Intelligence field, Confidence is often notated with the NATO Admiralty code.</p> <p>Why Confidence instead of Credibility?</p> <p>Using both Reliability and Credibility is an advanced use case for most of CTI teams. It requires a mature organization and a well staffed team. For most of internal CTI team, a simple confidence level is enough to forge assessment, in particular for teams that concentrate on technical CTI. </p> <p>Thus in OpenCTI, we have made the choice to fuse the notion of Credibility with the Confidence level that is commonly used by the majority of users. They have now the liberty to push forward their practice and use both Confidence and Reliability in their daily assessments.</p>"},{"location":"usage/reliability-confidence/#reliability-open-vocabulary","title":"Reliability open vocabulary","text":"<p>Reliability value can be set for every Entity in the platform that can be Author of Knowledge:</p> <ul> <li><code>Organizations</code></li> <li><code>Individuals</code></li> <li><code>Systems</code></li> <li>and also <code>Reports</code></li> </ul> <p>Reliability on <code>Reports</code> allows you to specify the reliability associated to the original author of the report if you received it through a provider.</p> <p>For all Knowledge in the platform, the reliability of the source of the Knowledge (author) is displayed in the Overview. This way, you can always forge your assessment of the provided Knowledge regarding the reliability of the author.</p> <p></p> <p>You can also now filter entities by the reliability of its author.</p> <p>Tip</p> <p>This way, you may choose to feed your work with only Knowledge provided by reliable sources.</p> <p>Reliability is an open vocabulary that can be customized in Settings -&gt; Taxonomies -&gt; Vocabularies : reliability_ov. </p> <p>Info</p> <p>The setting by default is the Reliability scale from NATO Admiralty code. But you can define whatever best fit your organization.</p> <p></p>"},{"location":"usage/reliability-confidence/#confidence-scale","title":"Confidence scale","text":"<p>Confidence level can be set for:</p> <ul> <li>Analyses: <code>Report</code>, <code>Grouping</code>, <code>Malware analysis</code>, <code>Notes</code></li> <li>Cases: <code>Incident Response</code>, <code>Request for Information</code>, <code>Request for Takedown</code>, <code>Feedback</code></li> <li>Events: <code>Incident</code>, <code>Sighting</code>, <code>Observed data</code></li> <li>Observations: <code>Indicator</code>, <code>Infrastructure</code></li> <li>Threats: <code>Threat actor (Group)</code>, <code>Threat actor (Individual)</code>, <code>Intrusion Set</code>, <code>Campaign</code></li> <li>Arsenal: <code>Malware</code>, <code>Channel</code>, <code>Tool</code>, <code>Vulnerability</code></li> </ul> <p>For all of these entities, the Confidence level is displayed in the Overview, along with the Reliability. This way, you can rapidly assess the Knowledge with the Confidence level representing the credibility/quality of the information.</p>"},{"location":"usage/reliability-confidence/#confidence-scale-customization","title":"Confidence scale customization","text":"<p>Confidence level is a numerical value between 0 and 100. But Multiple \"Ticks\" can be defined and labelled to provide a meaningful scale.</p> <p>Confidence level can be customized for each entity type in Settings &gt; Customization &gt; Entity type.</p> <p></p> <p>As such customization can be cumbersome, three confidence level templates are provided in OpenCTI:</p> <ul> <li>Admiralty: corresponding to the Admiralty code's credibility scale</li> <li>Objective: corresponding to a full objective scale, aiming to leave any subjectivity behind. With this scale, an information confidence is:<ul> <li>\"Cannot be judged\": there is no data regarding the credibility of the information</li> <li>\"Told\": the information is known because it has been told to the source. The source doesn't verify it by any means.</li> <li>\"Induced\": the information is the result of an analysis work and is based on other similar information assumed to be true.</li> <li>\"Deduced\": the information is the result of an analysis work, and is a logical conclusion of other information assumed to be true.</li> <li>\"Witnessed\": the source have observed itself the described situation or object.</li> </ul> </li> <li>standard: the historic confidence level scale in OpenCTI defining a Low, Med and High level of confidence.</li> </ul> <p>It is always possible to modify an existing template to define a custom scale adapted to your context.</p> <p>Tip</p> <p>If you use the Admiralty code setting for both reliability and Confidence, you will find yourself with the equivalent of NATO confidence notation in the Overview of your different entities (A1, B2, C3, etc.)</p> <p></p>"},{"location":"usage/reliability-confidence/#max-confidence-level","title":"Max confidence level","text":""},{"location":"usage/reliability-confidence/#overview","title":"Overview","text":"<p>We know that in organizations, different users do not always have the same expertise or seniority.  As a result, some specific users can be more \"trusted\" when creating or updating knowledge than others. Additionally, because connectors, TAXII feeds and streams are all linked to respectively one user, it is important to be able to differentiate which connector, stream or TAXII feed is more trustable than others.</p> <p>This is why we have introduced the concept of max confidence level to tackle this use case.</p> <p>Max confidence level per user allows organizations to fine tune their users to ensure knowledge updated and created stays as consistent as possible.</p> <p>The maximum confidence level can be set at the Group level or at the User level, and can be overridden by entity type for fine-tuning your confidence policy.</p>"},{"location":"usage/reliability-confidence/#overall-way-of-working","title":"Overall way of working","text":"<p>The overall idea is that users with a max confidence level lower than a confidence level of an entity cannot update or delete this entity.</p> <p>Also, in a conservative approach, when 2 confidence levels are possible, we would always take the lowest one.</p> <p>To have a detailed understanding of the concept, please browse through this diagram:</p>"},{"location":"usage/reliability-confidence/#user-effective-confidence-level","title":"User effective confidence level","text":"<p>User and group confidence level configuration shall be viewed as:</p> <ul> <li>a maximum confidence level between 0 and 100 (optional for users, mandatory for groups);</li> <li>a list of overrides (a max confidence level between 0 and 100) per entity type (optional).</li> </ul> <p>The user's effective confidence level is the result of this configuration from multiple sources (user and their groups).</p> <p>To compute this value, OpenCTI uses the following strategy:</p> <ul> <li>effective maximum confidence is the maximum value found in the user's groups;</li> <li>effective overrides per entity type are cumulated from all groups, taking the maximum value if several overrides are set on the same entity type</li> <li>if a user maximum confidence level is set, it overrides everything from groups, including the overrides per entity type defined at group level</li> <li>if not, but the user has specific overrides per entity types, they override the corresponding confidence levels per entity types coming from groups</li> <li>if a user has the administrator's \"Bypass\" capability, the effective confidence level will always be 100 without overrides, regardless of the group and user configuration on confidence level</li> </ul> <p>The following diagram describes the different use-cases you can address with this system.</p>"},{"location":"usage/reliability-confidence/#how-to-set-a-confidence-level","title":"How to set a confidence level","text":"<p>You can set up a maximum confidence levels from the Confidences tab in the edition panel of your user or group. The value can be selected between 0 and 100, or using the admiralty scale selector.</p> <p>At the group level, the maximum confidence level is mandatory, but is optional at the user level (you have to enable it using the corresponding toggle button).</p> <p></p>"},{"location":"usage/reliability-confidence/#how-to-override-a-max-confidence-level-per-entity-type","title":"How to override a max confidence level per entity type","text":"<p>You also have the possibility to override a max confidence level per entity type, limited to Stix Domain Objects. </p> <p></p> <p>You can visualize the user's effective confidence level in the user's details view, by hovering the corresponding tooltip. It describes where the different values might come from.</p> <p></p>"},{"location":"usage/reliability-confidence/#usage-in-opencti","title":"Usage in OpenCTI","text":""},{"location":"usage/reliability-confidence/#example-with-the-admiralty-code-template","title":"Example with the admiralty code template","text":"<p>Your organization have received a report from a CTI provider. At your organization level, this provider is considered as reliable most of the time and its reliability level has been set to \"B - Usually Reliable\" (your organization uses the Admiralty code).</p> <p>This report concerns ransomware threat landscape and have been analysed by your CTI analyst specialized in cybercrime. This analyst has granted a confidence level of \"2 - Probably True\" to the information. </p> <p>As a technical analyst, through the cumulated reliability and Confidence notations, you now know that the technical elements of this report are probably worth consideration.</p> <p></p>"},{"location":"usage/reliability-confidence/#example-with-the-objective-template","title":"Example with the Objective template","text":"<p>As a CTI analyst in a governmental CSIRT, you build up Knowledge that will be shared within the platform to beneficiaries. Your CSIRT is considered as a reliable source by your beneficiaries, even if you play a role of a proxy with other sources, but your beneficiaries need some insights about how the Knowledge has been built/gathered. </p> <p>For that, you use the \"Objective\" confidence scale in your platform to provide beneficiaries with that. When the Knowledge is the work of the investigation of your CSIRT, either from incident response or attack infrastructure investigation, you set the confidence level to \"Witnessed\", \"Deduced\" or \"Induced\" (depending on if you observed directly the data, or inferred it during your research). When the information has not been verified by the CSIRT but has value to be shared with beneficiaries, you can use the \"Told\" level to make it clear to them that the information is probably valuable but has not been verified.</p> <p></p>"},{"location":"usage/search/","title":"Search for knowledge","text":"<p>In OpenCTI, you have access to different capabilities to be able to search for knowledge in the platform. In most cases, a search by keyword can be refined with additional filters for instance on the type of object, the author etc.</p>"},{"location":"usage/search/#global-search","title":"Global search","text":"<p>The global search is always available in the top bar of the platform.</p> <p></p> <p>This search covers all STIX Domain Objects (SDOs) and STIX Cyber Observables (SCOs) in the platform. The search results are sorted according to the following behaviour:</p> <ul> <li>Priority 1 for exact matching of the keyword in one attribute of the objects.</li> <li>Priority 2 for partial matching of the keyword in the <code>name</code>, the <code>aliases</code> and the <code>description</code> attributes (full text search).</li> <li>Priority 3 for partial matching of the keyword in all other attributes (full text search).</li> </ul> <p>If you get unexpected result, it is always possible to add some filters after the initial search:</p> <p></p> <p>Also, using the <code>Advanced search</code> button, it is possible to directly put filters in a global search:</p> <p></p> <p>Advanced filters</p> <p>You have access to advanced filters all accross the UI, if you want to know more about how to use these  filters with the API or the Python library, don't hesitate to read the dedicated page</p>"},{"location":"usage/search/#full-text-search-in-files-content","title":"Full text search in files content","text":"<p>Enterprise edition</p> <p>Full text search in files content is available under the \"OpenCTI Enterprise Edition\" license.</p> <p>Please read the dedicated page to have all information</p> <p>It's possible to extend the global search by keywords to the content of documents uploaded to the platform via the Data import tab, or directly linked to an entity via its Data tab.</p> <p>It is particularly useful to enable <code>Full text indexing</code> to avoid missing important information that may not have been structured within the platform. This situation can arise due to a partial automatic import of document content, limitations of a connector, and, of course, errors during manual processing.</p> <p></p> <p>In order to search in files, you need to configure file indexing.</p>"},{"location":"usage/search/#bulk-search","title":"Bulk search","text":"<p>The bulk search capabilities is available in the top bar of the platform and allows you to copy paste a list of keyword or objects (ie. list of domains, list of IP addresses, list of vulnerabilities, etc.) to search in the platform:</p> <p></p> <p>When searching in bulk, OpenCTI is only looking for an exact match in some properties:</p> <ul> <li><code>name</code></li> <li><code>aliases</code></li> <li><code>x_opencti_aliases</code></li> <li><code>x_mitre_id</code></li> <li><code>value</code></li> <li><code>subject</code></li> <li><code>abstract</code></li> <li><code>hashes.MD5</code></li> <li><code>hashes.SHA-1</code></li> <li><code>hashes.SHA-256</code></li> <li><code>hashes.SHA-512</code></li> <li><code>x_opencti_additional_names</code></li> </ul> <p>When something is not found, it appears in the list as <code>Unknown</code> and will be excluded if you choose to export your search result in a JSON STIX bundle or in a CSV file.</p> <p></p>"},{"location":"usage/search/#contextual-search","title":"Contextual search","text":"<p>In most of the screens of knowledge, you always have a contextual search bar allowing you to filter the list you are on:</p> <p></p> <p>The search keyword used here is taken into account if you decide to export the current view in a file such as a JSON STIX bundle or a CSV file.</p>"},{"location":"usage/search/#other-search-bars","title":"Other search bars","text":"<p>Some other screens can contain search bars for specific purposes. For instance, in the graph views to filter the nodes displayed on the graph:</p> <p></p>"},{"location":"usage/tips-widget-creation/","title":"Pro-tips on widget creation","text":"<p>Previously, the creation of widgets has been covered. To help users being more confident in creating widgets, here are some details to master the widget creation.</p> <p></p>"},{"location":"usage/tips-widget-creation/#how-to-choose-the-appropriate-widget-visualization-for-your-use-case","title":"How to choose the appropriate widget visualization for your use case?","text":"<p>We can classify the widgets in 3 different types.</p>"},{"location":"usage/tips-widget-creation/#single-dimension-widgets","title":"Single dimension widgets","text":"<p>Use these widgets when you would like to display information about one single type of object (entity or relation).</p> <ul> <li>Widget visualizations: number, list, list (distribution), timeline, donuts, radar, map, bookmark, tree map.</li> <li>Use case example: view the amount of malware in platform (number widget), view the top 10 threat actor group target a specific country (distribution list widget), etc.</li> </ul>"},{"location":"usage/tips-widget-creation/#multi-dimension-widgets","title":"Multi dimension widgets","text":"<p>Use these widgets if you would like to compare or have some insights about similar types of object (up to 5).</p> <ul> <li>Widget visualizations: line, area, heatmap, vertical bars.</li> <li>Use case example: view the amount of malware, intrusion sets, threat actor groups added in the course of last month in the platform (line or area widget).</li> </ul> <p>Type of object in widget</p> <p>These widgets need to use the same \"type\" of object to work properly. You always need to add relationships in the filter view if you have selected a \"knowledge graph\" perspective. If you have selected the knowledge graph entity, adding \"Entities\" (click on <code>+ entities</code>) will not work, since you are not counting the same things.</p>"},{"location":"usage/tips-widget-creation/#break-down-widgets","title":"Break down widgets","text":"<p>Use this widget if you want to divide your data set into smaller parts to make it clearer and more useful for analysis.</p> <ul> <li>Widget visualization: horizontal bars.</li> <li>Use case example: view the list of malware targeting a country breakdown by the type of malware.</li> </ul> <p></p>"},{"location":"usage/tips-widget-creation/#adding-datasets-to-your-widget","title":"Adding datasets to your widget","text":"<p>Adding datasets can serve two purposes: comparing data or breakdown a view to have deeper understanding on what a specific dataset is composed of. </p>"},{"location":"usage/tips-widget-creation/#use-case-1-compare-several-datasets","title":"Use Case 1: compare several datasets","text":"<p>As mentioned in How to choose the appropriate widget visualization for your use case? section you can add data sets to compare different data. Make sure to add the same type of objects (entities or relations) to be able to compare the same objects, by using access buttons like <code>+</code>, <code>+ Relationships</code>, or <code>+ Entities</code>.</p> <p>You can add up to 5 different data sets.  The <code>Label</code> field allows you to name a data set, and this label can then be shown as a legend in the widget using the <code>Display legend</code> button in the widget parameters (see the next section).</p>"},{"location":"usage/tips-widget-creation/#use-case-2-break-down-your-chart","title":"Use case 2: break down your chart","text":"<p>As mentioned in How to choose the appropriate widget visualization for your use case? section you can add data sets to decompose your graph into smaller meaningful chunks. In the below points, you can find some use cases that will help you understand how to structure your data.</p> <p>You can break down a view either by entity or by relations, depending on what you need to count.</p>"},{"location":"usage/tips-widget-creation/#break-down-by-entity","title":"Break down by entity","text":"<p>Use case example: I need to understand what are the most targeted countries by malware, and have a breakdown for each country by malware type.</p> <p>Process:</p> <ol> <li>To achieve this use case, you first need to select the horizontal bar vizualisation.</li> <li>Then you need to select the knowledge graph perspective.</li> </ol> <p>In the filters view:</p> <ol> <li>Then input your main query <code>Source type = Malware AND Target type = Countries AND Relation type = Targets</code>. Add a label to your dataset. </li> <li>Add an entity data set by using access button <code>+ Entities</code>.</li> <li>Add the following filters <code>Entity type = Malware AND In regards of = targets</code>. Add a label to your dataset.</li> </ol> <p></p> <p>In the parameter view:</p> <ol> <li>Attribute (of your relation) = entity (so that you display the different entities values)</li> <li>Display the source toggle = off</li> <li>Attribute (of your entity malware) = Malware type (since you want to break down your relations by the malware types)</li> </ol> <p></p> <p>As a result, you get a list of countries broken down by malware types.</p> <p></p>"},{"location":"usage/tips-widget-creation/#break-down-by-relation","title":"Break down by relation","text":"<p>Use case example: I need to understand what are the top targeting malware and have a breakdown of the top targets per malware</p> <p>Process:</p> <ol> <li>To achieve this use case, you first need to select the horizontal bar vizualisation.</li> <li>Then you need to select the knowledge graph perspective.</li> </ol> <p>In the filters view:</p> <ol> <li>Then input your main query <code>Source type = Malware AND Relation type = Targets</code>. Add a label to your dataset. </li> <li>Add a relation data set by using access button  <code>+ Relationships</code></li> <li>Add the following filters <code>Source type = Malware AND Relation type = targets</code>. Add a label to your dataset.</li> </ol> <p></p> <p>In the parameter view:</p> <ol> <li>Attribute (of your relation): entity (so that you display the different entities values)</li> <li>Display the source toggle = on</li> <li>Attribute (of your entity malware) = Malware type (since you want to break down your relations by the malware types)</li> <li>Display the source toggle = off</li> </ol> <p></p> <p>As a result, you get a list of malware with the breakdown of their top targets.</p> <p></p>"},{"location":"usage/tips-widget-creation/#more-use-cases","title":"More use cases","text":"<p>To see more use cases, feel free to have a look at this blog post that will provide you additional information.</p>"},{"location":"usage/widgets/","title":"Widget creation","text":"<p>Creating widgets on the dashboard involves a four-step configuration process. By navigating through these configuration steps, users can design widgets that meet their specific requirements.</p>"},{"location":"usage/widgets/#widget-configuration","title":"Widget configuration","text":""},{"location":"usage/widgets/#1-visualization","title":"1. Visualization","text":"<p>Users can select from 15 diverse visualization options to highlight different aspects of their data. This includes simple views like counters and lists, as well as more intricate views like heatmaps and trees. The chosen visualization impacts the available perspectives and parameters, making it crucial to align the view with the desired data observations. Here are a few insights:</p> <ul> <li>Line and Area views: Ideal for visualizing activity volumes over time.</li> <li>Horizontal bar views: Designed to identify top entities that best satisfy applied filters (e.g., top malware targeting the Finance sector).</li> <li>Tree views: Useful for comparing activity volumes.</li> <li>...</li> </ul> <p></p>"},{"location":"usage/widgets/#2-perspective","title":"2. Perspective","text":"<p>A perspective is the way the platform will count the data to display in your widgets:</p> <ul> <li>Entities Perspective: Focuses on entities, allowing observation of simple knowledge based on defined filters and criteria. The count will be based on entities only.</li> <li>Knowledge Graph Perspective: Concentrates on relationships, displaying intricate knowledge derived from relationships between entities and specified filters.  The count will be based on relations only.</li> <li>Activity &amp; History Perspective: Centers on activities within the platform, not the knowledge content. This perspective is valuable for monitoring user and connector activities, evaluating data sources, and more.</li> </ul> <p></p>"},{"location":"usage/widgets/#3-filters","title":"3. Filters","text":""},{"location":"usage/widgets/#generic-knowledge","title":"Generic knowledge","text":"<p>Filters vary based on the selected perspective, defining the dataset to be utilized in the widget. Filters are instrumental in narrowing down the scope of data for a more focused analysis.</p> <p>While filters in the \"Entities\" and \"Activity &amp; History\" perspectives align with the platform's familiar search and feed creation filters, the \"Knowledge Graph\" perspective introduces a more intricate filter configuration.Therefore, they need to be addressed in more detail.</p>"},{"location":"usage/widgets/#filter-in-the-context-of-knowledge-graph","title":"Filter in the context of Knowledge Graph","text":"<p>Two types of filters are available in the Knowledge Graph perspective:</p> <ul> <li> <p>Main query filter</p> <ul> <li>Classic filters (gray): Define the relationships to be retrieved, forming the basis on which the widget displays data. Remember, statistics in the Knowledge Graph perspective are based on relationships.</li> </ul> </li> <li> <p>Pre-query filters</p> <ul> <li>Pre-query filters are used to provide to your main query a specific dataset. In other words, instead of making a query on the whole data set of your platform, you can already target a subset of data that will match certain criteria. They are two types of pre-query filters:<ul> <li>Dynamic filters on the source (orange): Refine data by filtering on entities positioned as the source (in the \"from\" position) of the relationship.</li> <li>Dynamic filters on the target (green): Refine data by filtering on entities positioned as the target (in the \"to\" position) of the relationship.</li> </ul> </li> </ul> </li> </ul> <p>Pre-query limitation</p> <p>The pre-query is limited to 5000 results. If your pre-query results in having more than 5000 results, your widget will only display statistics based on these 5000 results matching your pre-query, resulting in a wrong view. To avoid this issue, be specific in your pre-query filters.</p> <p>Example scenario:</p> <p>Let's consider an example scenario: Analyzing the initial access attack patterns used by intrusion sets targeting the finance sector.</p> <ol> <li>Classic filters: Define the relationships associated with the use of attack patterns by intrusion sets</li> <li>Dynamic filters on the source (Orange): Narrow down the data by filtering on intrusion sets targeting the finance sector.</li> <li>Dynamic filters on the target (Green): Narrow down the data by filtering on attack patterns associated with the kill chain's initial access phase.</li> </ol> <p>By leveraging these advanced filters, users can conduct detailed analyses within the Knowledge Graph perspective, unlocking insights that are crucial for understanding intricate relationships and statistics.</p> <p></p> <p>In certain views, you can access buttons like <code>+</code>, <code>+ Relationships,</code> or <code>+ Entities</code>. These buttons enable you to incorporate different data into the same widget for comparative analysis. For instance, in a Line view, adding a second set of filters will display two curves in the widget, each corresponding to one of the filtered data sets. Depending on the view, you can work with 1 to 5 sets of filters. The <code>Label</code> field allows you to name a data set, and this label can then be shown as a legend in the widget using the <code>Display legend</code> button in the widget parameters (see the next section).</p> <p></p>"},{"location":"usage/widgets/#4-parameters","title":"4. Parameters","text":"<p>Parameters depend on the chosen visualization and allow users to define widget titles, choose displayed elements from the filtered data, select data reference date, and configure various other parameters specific to each visualization.</p> <p>For the \"Knowledge Graph\" perspective, a critical parameter is the <code>Display the source</code> toggle. This feature empowers users to choose whether the widget displays entities from the source side or the target side of the relationships.</p> <ul> <li>Toggle ON (\"Display the source\"): The widget focuses on entities positioned as the source of the relationships (in the \"from\" position).</li> <li>Toggle OFF (\"Display the target\"): The widget shifts its focus to entities positioned as the target of the relationships (in the \"to\" position).</li> </ul> <p>This level of control ensures that your dashboard aligns precisely with your analytical objectives, offering a tailored perspective based on your data and relationship.</p> <p></p>"},{"location":"usage/widgets/#prerequisite-knowledge","title":"Prerequisite knowledge","text":"<p>To successfully configure widgets in OpenCTI, having a solid understanding of the platform's data modeling is essential. Knowing specific relationships, entities, and their attributes helps refine filters accurately. Let's explore two examples.</p> <p>Scenarios 1:</p> <p>Consider the scenario where you aim to visualize relationships between intrusion sets and attack patterns. In this case, the relevant relationship type connecting intrusion sets to attack patterns is labeled as \"Uses\" (as illustrated in the \"Filters\" section).</p> <p>Scenarios 2:</p> <p>Suppose your goal is to retrieve all reports associated with the finance sector. In this case, it's essential to use the correct filter for the finance sector. Instead of placing the finance sector in the \"Related entity\" filter, it should be placed in the \"Contains\" filter. Since a Report is a container object (like Cases and Groupings), it contains entities within it and is not related to entities.</p>"},{"location":"usage/widgets/#key-data-modeling-aspects","title":"Key data modeling aspects","text":"<ul> <li>Entities: Recognizing container (e.g. Reports, Cases and Groupings) and understanding the difference with non-container.</li> <li>Relationships: Identifying the relationship types connecting entities.</li> <li>Attributes: Understanding entities and relationships attributes for effective filtering.</li> </ul> <p>Having this prerequisite knowledge allows you to navigate the widget configuration process seamlessly, ensuring accurate and insightful visualizations based on your specific data requirements.</p>"},{"location":"usage/workbench/","title":"Analyst workbench","text":"<p>Workbenches serve as dedicated workspaces for manipulating data before it is officially imported into the platform. </p>"},{"location":"usage/workbench/#location-of-use","title":"Location of use","text":"<p>The workbenches are located at various places within the platform:</p>"},{"location":"usage/workbench/#data-import-and-analyst-workbenches-window","title":"Data import and analyst workbenches window","text":"<p>This window encompasses all the necessary tools for importing a file. Files imported through this interface will subsequently be processed by the import connectors, resulting in the creation of workbenches. Additionally, analysts can manually create a workbench by clicking on the \"+\" icon at the bottom right of the window.</p> <p></p>"},{"location":"usage/workbench/#data-tabs-of-all-entities","title":"Data tabs of all entities","text":"<p>Workbenches are also accessible through the \"Data\" tabs of entities, providing convenient access to import data associated with the entity.</p> <p></p>"},{"location":"usage/workbench/#operation","title":"Operation","text":"<p>Workbenches are automatically generated upon the import of a file through an import connector. When an import connector is initiated, it scans files for recognizable entities and subsequently creates a workbench. All identified entities are placed within this workbench for analyst reviews. Alternatively, analysts have the option to manually create a workbench by clicking on the \"+\" icon at the bottom right of the \"Data import and analyst workbenches\" window.</p> <p></p> <p>The workbench being a draft space, the analysts use it to review connector proposals before finalizing them for import. Within the workbench, analysts have the flexibility to add, delete, or modify entities to meet specific requirements.</p> <p></p> <p>Once the content within the workbench is deemed acceptable, the analyst must initiate the ingestion process by clicking on <code>Validate this workbench</code>. This action signifies writing the data in the knowledge base.</p> <p>Workbenches are drafting spaces</p> <p>Until the workbench is validated, the contained data remains in draft form and is not recorded in the knowledge base. This ensures that only reviewed and approved data is officially integrated into the platform.</p> <p>For more information on importing files, refer to the Import from files documentation page.</p> <p>Confidence level of created knowledge through workbench</p> <p>The confidence level of knowledge created through workbench is affected by the confidence level of the user. Please navigate to this page to understand in more details.</p>"},{"location":"usage/workflows/","title":"Workflows and assignation","text":"<p>Efficiently manage and organize your work within the OpenCTI platform by leveraging workflows and assignment. These capabilities provide a structured approach to tracking the status of objects and assigning responsibilities to users.</p>"},{"location":"usage/workflows/#workflows","title":"Workflows","text":"<p>Workflows are designed to trace the status of objects in the system. They are represented by the \"Processing status\" field embedded in each object. By default, this field is disabled for most objects but can be activated through the platform settings. For details on activating and configuring workflows, refer to the dedicated documentation page.</p> <p>Enabling workflows enhances visibility into the progress and status of different objects, providing a comprehensive view for effective management.</p> <p></p>"},{"location":"usage/workflows/#assignment-attributes","title":"Assignment attributes","text":"<p>Certain objects, including Reports, Cases, and Tasks, come equipped with \"Assignees\" and \"Participants\" attributes. These attributes serve the purpose of designating individuals responsible for the object and those who actively participate in it.</p> <p>Attributes can be set as mandatory or with default values, streamlining the assignment process. Users can also be assigned or designated as participants manually, contributing to a collaborative and organized workflow. For details on configuring attributes, refer to the dedicated documentation page.</p> <p></p> <p>Users can stay informed about assignments through notification triggers. By setting up notification triggers, users receive alerts when an object is assigned to them. This ensures timely communication and proactive engagement with assigned tasks or responsibilities.</p>"}]}
\ No newline at end of file
diff --git a/6.1.X/sitemap.xml b/6.1.X/sitemap.xml
index cc658690..8cfd6cba 100755
--- a/6.1.X/sitemap.xml
+++ b/6.1.X/sitemap.xml
@@ -2,457 +2,457 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://docs.opencti.io/latest/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/csv-mappers/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/decay-rules/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/enterprise/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/entities/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/file-indexing/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/introduction/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/merging/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/notifier-samples/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/notifiers/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/ontologies/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/organization-segregation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/parameters/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/policies/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/reasoning/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/retentions/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/segregation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/support-package/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/users/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/audit/configuration/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/audit/events/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/audit/overview/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/administration/audit/triggers/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/authentication/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/clustering/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/configuration/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/connectors/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/installation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/integrations/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/managers/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/map/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/overview/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/resources/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/rollover/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/troubleshooting/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/deployment/upgrade/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/api-usage/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/connectors/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/environment_ubuntu/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/environment_windows/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/platform/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/development/python/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/api/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/data-intelligence/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/data-model/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/filters-migration/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/filters/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/fips/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/streaming/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/taxonomy/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/reference/usage-telemetry/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/ask-ai/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/automation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/background-tasks/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/case-management/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/containers/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/dashboards-share/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/dashboards/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/data-model/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/dates/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/deduplication/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/delete-restore/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/enrichment/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-analysis/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-arsenal/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-cases/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-entities/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-events/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-locations/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-observations/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-techniques/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/exploring-threats/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/export/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/feeds/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/getting-started/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/import-automated/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/import-files/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/indicators-lifecycle/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/inferences/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/manual-creation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/merging/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/nested/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/notifications/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/overview/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/pivoting/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/reliability-confidence/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/search/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/tips-widget-creation/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/widgets/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/workbench/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.opencti.io/latest/usage/workflows/</loc>
-         <lastmod>2024-05-29</lastmod>
+         <lastmod>2024-06-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/6.1.X/sitemap.xml.gz b/6.1.X/sitemap.xml.gz
index 025193ab6c7b93388979fbbe0e73c734c4cc1734..eecb204d4a9e69c43e895fa785331b55673a9bd4 100755
GIT binary patch
delta 921
zcmV;K17`fE2c`!HABzYG;F(*I2OWPoJDpD3@jACYL3{4dBqU*$A{YR)*M0g@)+TY2
zTMr#V7gIDP{S1S^pC3AYdRx-d1z3>s%kJa;uzP|WC}N&oc7OiyyZdGL>Ga`PISJ@f
zYn<g}H>;N4hT(d>?gbSVUt~`_4HD*dBEx&-aM=I4JAHU+$9jXUbU%)X!fAiKi?rKB
z3hnaJ9;>)V8j@EK9gf4==<ymax==hlAD(}5ho9ZyxixvOduSGBpC=d@KA)n;bUO|Y
zH5<(EmF7Qi`M6+4QTEzwHUzo2_FGFcp%vr^!QUL$1ZI#SD{x^HFhq=sb}T$%0*5)m
zTkHB(pfM{`tl@rQgn0p;44Hp8lj4ZLPW(~~MT{@pW`HRxC7KL{jF$3!#=q|;PGDk~
zyrrI4Jo^RIkdG8f7z}v`gBQw%q8&GP$ZN@ri4FEUsihFBD?YsX$&8|_VklDh8c~Np
zdBmx*DfigW;nF&yF>_NJNM8`Hwy2eHntFEa2qn>NY5vfNbzTE>=-YpzABaP$(j-RD
zIq;FzM8NnraE72{!+kM}`jpIAw~eoxyzqSsq6gl^XKy8xtrMgMFuTub53CGAl>?ag
z|Cv%+jcb8bnd&)#%tUG=lhx7!SA>pHFOaBgs-~c;((_R0k=8`Y{e}zqf=qcW|5eX5
zYc+>`#T@Bs!`!9Sjl_S84cME`9V;=05x7;t8X*i&Mz7wjnlUAu?lnf3+tVQ#fE_Wd
z)75Ulsq-P)56mV=iv>(k2EX(y!@jYqf1^yx%>e3MfVmdCU;*WRi8rC><<)uY9kMDd
zeaEQ{^z6gy)W$eDI&GGf&T)emaNAtRUB+}yOIbbUo^!wk8ohtaXYw4y$?O@-;C2t%
zy~O$o3f&tMVlAon1&}YS2^1W+8tT3~L1qlIfp`jUCDFQ|<XQ$uH$kxj%mR(s4DXs~
z?O3<_EvG*K_r1pdJ#M?C^QExwiRmoB7h}*0Vb1uu8ggWv+mPIXClmLc-9~`!1?>d7
zE`vEy&kC_~T3mnbyY1cw<5qCj_Yr#c1I%$1;>6+-ju37kLHEe-^Ig5$cJaCT<iZ+Q
z`yc7_{!+(AnOm{@{=dDrVMA$kzd2^ZEO_aA-^PZ?kkFqoq2AnmBVz1&4RM1O@EqpO
vAr*_bE5;^VtVGm}w)X&VC4N1(uVw?BWBOnAkla56^z;c2mELqtTs{B*7c|aX

delta 922
zcmV;L17-ZC2d4)IABzYG;8RwS2OWQHcbb`|<8^L*g5=zxNl3yhMKAzpuk-Y!tWDx3
zw;no#E~aQo`WXg+KR<N%_`0NrGq51#=iP7n$K3<uKoRrwy!-s=FZajp<MG|0auU#o
z);P=aZdNUS4#VYg*$XNxzQ~?<8YIl^M25G@;c@?AcYOEIj`apx>2@3vh2wvE7iqVN
z6x!vbJyvm#G$gMeIvj?z(fu`EbfI{BdVKobJ-&BOA6k>Qy1Qm!_IZMl;ma|4OxMG3
zSF^zk-)a5>myZi(6lJf?W<!v(YrnNL6Iwxz5d76~O<)EYvH}-I0Yk*7Xve}MCUBS|
zytb}y1sbz5#TsrWMwl1i$&i1EGbxS;?8Gm{P{jDgZ3dXKQliOF$Y?3wXZ(6QaRL*=
z<Sq5Y;@K~thJ2(@!eGcl7`#w66z#aVLtaZ}Ol+{<NiBs~UGd??Pi7Qd6+@B2*N8d<
z$|FvdO}WR04(HYpjhUO;K>Cbuu|=(n)6}zTM<|J|OY?_Dtn(V6L*IWMeMcNpl_oKI
z&Vl!|CIZI4finap8}5r))Td;|x@~;j<c05B5Z&=EK6@*nY@HxAfZ2UcyJKY#svN+?
z|Id`tYFrDf%2ZDYWF}H0nXHx;xFU3ndWJ-0Q#A!$m7a$}_p~Nb?hjnZXJpE2`R{tF
zS*tnh3+6}{8|E&pZX|zRY`|W1?pTR2jKHlD)(ByMGJ5rH)r=|ObgMDK+@21}0PKiq
zovwBZPMr_YeqlC2S}b6SGWexu8TNx!{VQc!t_DzV0?f781q&$mOS}n1FE7qx?~qk#
z={rtspeG+*rZ&dO(P^`+bdDRmfZOIeZZf8GTFUA%_nZSZ(CB|<K9T1rPG-+w2Df|A
z?j_cDQ0U&65Nk=jFMxbwO`zbo)lm1{2{L1t4a8G;Es53zCD$@Qx(bRNU>0c1W_Z^`
zYsb3XZ#n%1xbHRopK;qIoiBy`OiU*MJ{yBp2y@0S)sQ3W+=k>9Jej!n>^1^)FK8#w
zbs5ZwdRB;?)8c<}+imwY7`KAEzK_tmA7GBF5GNLwaD;FT3A#sqoA2t~wu{fzCl}Vh
z+W$zW_m?_0%G`?G_y6t14I4_U`^_;MX2Emc`!+UAhJ^lv3H9o38xdpIYls`PfafrG
w4yjngT`)G`VkM$(w7my_3-QaTeKi~49Mk`@hvfDlpvMY-0HVv#30yt^05&wql>h($

diff --git a/6.1.X/usage/assets/group-confidence-overrides.png b/6.1.X/usage/assets/group-confidence-overrides.png
new file mode 100755
index 0000000000000000000000000000000000000000..5ffe719c51fc6c26387156109a6c98bd95bab355
GIT binary patch
literal 43287
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
PquKs_k$b7TPh9*ba})~U

literal 0
HcmV?d00001

diff --git a/6.1.X/usage/assets/override-confidence-tooltip.png b/6.1.X/usage/assets/override-confidence-tooltip.png
new file mode 100755
index 0000000000000000000000000000000000000000..9b499f05c29b8e8ab99431f8e0f4eef43cd3121f
GIT binary patch
literal 20525
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%0D^=QDQm3&oy`_rG4+`=2NZihP+vp0|AW
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

literal 0
HcmV?d00001

diff --git a/6.1.X/usage/assets/update-confidence-level.png b/6.1.X/usage/assets/update-confidence-level.png
new file mode 100755
index 0000000000000000000000000000000000000000..065c1db78488550c8f41134edb021e03b8cbb600
GIT binary patch
literal 31790
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

literal 0
HcmV?d00001

diff --git a/6.1.X/usage/assets/user-confidence-overrides.png b/6.1.X/usage/assets/user-confidence-overrides.png
new file mode 100755
index 0000000000000000000000000000000000000000..47d1ea1594391b9f654662daef31da9b944a7ca5
GIT binary patch
literal 44485
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

literal 0
HcmV?d00001

diff --git a/6.1.X/usage/reliability-confidence/index.html b/6.1.X/usage/reliability-confidence/index.html
index 3aa31fef..6a35d549 100755
--- a/6.1.X/usage/reliability-confidence/index.html
+++ b/6.1.X/usage/reliability-confidence/index.html
@@ -1447,6 +1447,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#user-effective-confidence-level" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        User effective confidence level
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1458,6 +1469,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#how-to-override-a-max-confidence-level-per-entity-type" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        How to override a max confidence level per entity type
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -4854,6 +4876,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#user-effective-confidence-level" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        User effective confidence level
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -4865,6 +4898,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#how-to-override-a-max-confidence-level-per-entity-type" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        How to override a max confidence level per entity type
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -5094,14 +5138,42 @@ <h4 id="overview">Overview</h4>
 <p>We know that in organizations, different users do not always have the same expertise or seniority.  As a result, some specific users can be more "trusted" when creating or updating knowledge than others. Additionally, because connectors, TAXII feeds and streams are all linked to respectively one user, it is important to be able to differentiate which connector, stream or TAXII feed is more trustable than others.</p>
 <p>This is why we have introduced the concept of max confidence level to tackle this use case.</p>
 <p>Max confidence level per user allows organizations to fine tune their users to ensure knowledge updated and created stays as consistent as possible.</p>
+<p>The maximum confidence level can be set at the Group level or at the User level, and can be overridden by entity type for fine-tuning your confidence policy.</p>
 <h4 id="overall-way-of-working">Overall way of working</h4>
 <p>The overall idea is that users with a max confidence level lower than a confidence level of an entity cannot update or delete this entity.</p>
 <p>Also, in a conservative approach, when 2 confidence levels are possible, we would always take the lowest one.</p>
 <p>To have a detailed understanding of the concept, please browse through this diagram:</p>
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FlVU6O39B76MJmtnzg9DbZZ%2FConfidence-Level---Documentation%3Ftype%3Dwhiteboard%26node-id%3D0%253A1%26t%3DPQWrdBF6iMGEp0bw-1" allowfullscreen></iframe>
 
+<h4 id="user-effective-confidence-level">User effective confidence level</h4>
+<p>User and group confidence level configuration shall be viewed as:</p>
+<ul>
+<li>a maximum confidence level between 0 and 100 (optional for users, mandatory for groups);</li>
+<li>a list of overrides (a max confidence level between 0 and 100) per entity type (optional).</li>
+</ul>
+<p>The user's effective confidence level is the result of this configuration from multiple sources (user and their groups).</p>
+<p>To compute this value, OpenCTI uses the following strategy:</p>
+<ul>
+<li>effective maximum confidence is the maximum value found in the user's groups;</li>
+<li>effective overrides per entity type are cumulated from all groups, taking the maximum value if several overrides are set on the same entity type</li>
+<li>if a user maximum confidence level is set, it overrides everything from groups, including the overrides per entity type defined at group level</li>
+<li>if not, but the user has specific overrides per entity types, they override the corresponding confidence levels per entity types coming from groups</li>
+<li>if a user has the administrator's "Bypass" capability, the effective confidence level will always be 100 without overrides, regardless of the group and user configuration on confidence level</li>
+</ul>
+<p>The following diagram describes the different use-cases you can address with this system.</p>
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://www.figma.com/board/cecHM2dDyOPoviw6qbVYK4/Effective-Confidence-Level-Computation---Documentation?node-id=0-1&t=ZSJNGb93mPAQRPVh-1" allowfullscreen></iframe>
+
 <h4 id="how-to-set-a-confidence-level">How to set a confidence level</h4>
-<p>To see how to set up the confidence level, please go in this <a href="../../administration/users/">page</a>.</p>
+<p>You can set up a maximum confidence levels from the Confidences tab in the edition panel of your user or group.
+The value can be selected between 0 and 100, or using the admiralty scale selector.</p>
+<p>At the group level, the maximum confidence level is mandatory, but is optional at the user level (you have to enable it using the corresponding toggle button).</p>
+<p><a class="glightbox" href="../assets/update-confidence-level.png" data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"><img alt="Update Confidence Level" src="../assets/update-confidence-level.png" /></a></p>
+<h4 id="how-to-override-a-max-confidence-level-per-entity-type">How to override a max confidence level per entity type</h4>
+<p>You also have the possibility to override a max confidence level per entity type, limited to Stix Domain Objects. </p>
+<p><a class="glightbox" href="../assets/user-confidence-overrides.png" data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"><img alt="Override Max Confidence Level Per Entity" src="../assets/user-confidence-overrides.png" /></a></p>
+<p>You can visualize the user's effective confidence level in the user's details view, by hovering the corresponding tooltip.
+It describes where the different values might come from.</p>
+<p><a class="glightbox" href="../assets/override-confidence-tooltip.png" data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"><img alt="Override Confidence Tooltip" src="../assets/override-confidence-tooltip.png" /></a></p>
 <h2 id="usage-in-opencti">Usage in OpenCTI</h2>
 <h3 id="example-with-the-admiralty-code-template">Example with the admiralty code template</h3>
 <p>Your organization have received a report from a CTI provider. At your organization level, this provider is considered as reliable most of the time and its reliability level has been set to "B - Usually Reliable" (your organization uses the Admiralty code).</p>
@@ -5134,7 +5206,7 @@ <h3 id="example-with-the-objective-template">Example with the Objective template
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-06T02:56:16+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-06</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-05-30T14:55:17+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-05-30</span>
   </span>
 
     
@@ -5162,6 +5234,16 @@ <h3 id="example-with-the-objective-template">Example with the Objective template
     
     <nav>
       
+        <a href="https://github.com/labo-flg" class="md-author" title="@labo-flg">
+          
+          <img src="https://avatars.githubusercontent.com/u/146674147?v=4&size=72" alt="labo-flg">
+        </a>
+      
+        <a href="https://github.com/SarahBocognano" class="md-author" title="@SarahBocognano">
+          
+          <img src="https://avatars.githubusercontent.com/u/98532359?v=4&size=72" alt="SarahBocognano">
+        </a>
+      
         <a href="https://github.com/Lhorus6" class="md-author" title="@Lhorus6">
           
           <img src="https://avatars.githubusercontent.com/u/70956706?v=4&size=72" alt="Lhorus6">
@@ -5172,12 +5254,13 @@ <h3 id="example-with-the-objective-template">Example with the Objective template
           <img src="https://avatars.githubusercontent.com/u/148041607?v=4&size=72" alt="nino-filigran">
         </a>
       
-        <a href="https://github.com/SouadHadjiat" class="md-author" title="@SouadHadjiat">
-          
-          <img src="https://avatars.githubusercontent.com/u/668192?v=4&size=72" alt="SouadHadjiat">
-        </a>
       
       
+        
+          <a href="https://github.com/OpenCTI-Platform/docs/blob/main/docs/usage/reliability-confidence.md" class="md-author md-author--more">
+            +1
+          </a>
+        
       
     </nav>
   </span>