docs: more improvements to documentation site

site/content/docs/intro/getting_started.md

@@ -18,12 +18,34 @@ seo:
   noindex: false # false (default) or true
 ---
 
-YARA-X is a re-incarnation of [YARA](https://virustotal.github.io/yara), a
-pattern matching tool designed with
-malware researchers in mind, but that can be used in many other use cases.
 
-This new incarnation intends to be faster, safer and more user-friendly than
-its predecesor.
+YARA-X is a re-incarnation of  [YARA](https://virustotal.github.io/yara), a
+pattern matching tool designed with malware researchers in mind. This new
+incarnation intends to be faster, safer and more user-friendly than its
+predecessor. The ultimate goal of YARA-X is to
+serve as the future replacement for YARA.
+
+With YARA-X you can create descriptions of malware families (or whatever you
+want to describe) based on textual or binary patterns. Each description (a.k.a.
+rule) consists of a set of patterns and a boolean expression which determine its
+logic. Let's see an example:
+
+```yara
+rule silent_banker : banker {
+    meta:
+        description = "This is just an example"
+        threat_level = 3
+        in_the_wild = true
+
+    strings:
+        $a = {6A 40 68 00 30 00 00 6A 14 8D 91}
+        $b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}
+        $c = "UVODFRYSIHLNWPEJXQZAKCBGMT"
+
+    condition:
+        $a or $b or $c
+}
+```
 
 ## Further reading
 

site/content/docs/modules/elf.md

@@ -49,11 +49,10 @@ Returns the TrendMicro's `telfhash` for the ELF file. This is a symbol hash for
 ELF files, just like `imphash` is an imports hash for PE files. With `telfhash`,
 you can cluster ELF files by similarity based on symbols.
 
-Find more information in
-TrendMicro's [whitepaper](https://documents.trendmicro.com/assets/pdf/TB_Telfhash-%20An%20Algorithm%20That%20Finds%20Similar%20Malicious%20ELF%20Files%20Used%20in%20Linux%20IoT%20Malware.pdf)
-or
+For more information
 visit [https://github.com/trendmicro/telfhash](https://github.com/trendmicro/telfhash)
-for tools other tools that compute the `telfhash`.
+or read
+TrendMicro's [whitepaper](https://documents.trendmicro.com/assets/pdf/TB_Telfhash-%20An%20Algorithm%20That%20Finds%20Similar%20Malicious%20ELF%20Files%20Used%20in%20Linux%20IoT%20Malware.pdf).
 
 ###### Example
 

site/content/docs/writing_rules/differences.md

@@ -9,7 +9,7 @@ menu:
   docs:
     parent: ""
     identifier: "differences"
-weight: 270
+weight: 280
 toc: true
 seo:
   title: "" # custom title (optional)

site/content/docs/writing_rules/external_variables.md

@@ -0,0 +1,84 @@
+---
+title: "External global variables"
+description: "How to use external variables in YARA-X"
+summary: ""
+date: 2023-09-07T16:13:18+02:00
+lastmod: 2023-09-07T16:13:18+02:00
+draft: false
+menu:
+  docs:
+    parent: ""
+    identifier: "external_variables"
+weight: 270
+toc: true
+seo:
+  title: "" # custom title (optional)
+  description: "" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  noindex: false # false (default) or true
+---
+
+External variables enable rules to depend on dynamic values from external
+sources. For instance, consider the following rule:
+
+```
+rule VariableExample1 {
+    condition:
+        ext_var == 10
+}
+```
+
+Here, `ext_var` is an external variable whose value is determined at
+run-time. External variables can be integers, strings, or booleans, depending
+on their assigned value.
+
+Integer variables can replace integer constants in conditions, while boolean
+variables can act as boolean expressions. For example:
+
+```yara
+rule VariableExample2 {
+    condition:
+        bool_ext_var or filesize < int_ext_var
+}
+```
+
+External variables of type `string` can be used with any operators that works
+on strings, like `contains`, `startswith`, `endswith`, etc. Let's see some
+examples:
+
+```yara
+rule ContainsExample {
+    condition:
+        string_ext_var contains "text"
+}
+
+rule CaseInsensitiveContainsExample {
+    condition:
+        string_ext_var icontains "text"
+}
+
+rule StartsWithExample {
+    condition:
+        string_ext_var startswith "prefix"
+}
+
+rule EndsWithExample {
+    condition:
+        string_ext_var endswith "suffix"
+}
+
+rule MatchesExample {
+    condition:
+        string_ext_var matches /[a-z]+/
+}
+```
+
+Every external variable used in your rules must be defined when the rules
+are being compiled. This can be done using the `--define` option (or `-d`) in
+the command-line tool, or by using the appropriate API.
+(like [this one](
+https://docs.rs/yara-x/latest/yara_x/struct.Compiler.html#method.define_global)
+in Rust or
+[this one]({{< ref "python.md" >}}#define_globalidentifier-value)
+in Python).
+