docs: publish blog post about the fmt command.

site/content/blog/the-fmt-command/index.md

@@ -0,0 +1,213 @@
+---
+title: "The fmt command"
+description: ""
+summary: ""
+date: 2024-10-03T00:00:00+01:00
+lastmod: 2024-10-03T00:00:00+01:00
+draft: false
+weight: 50
+categories: [ ]
+tags: [ ]
+contributors: [ "Victor M. Alvarez" ]
+pinned: false
+homepage: false
+seo:
+  title: "The fmt command" # custom title (optional)
+  description: "An introduction to the YARA-X automatic rule formatter" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  noindex: false # false (default) or true
+---
+
+Consistent code formatting isn't just about aesthetics; it makes code easier to
+read, understand, and maintain. For many programming languages, there are tools
+that help you enforce a consistent coding style across your codebase. Even
+though YARA is not a traditional programming language, maintaining a consistent
+style across all your YARA rules is also important, especially when
+collaborating with a team or working on a large set of signatures. However,
+until now, the YARA community lacked a way to guarantee a homogeneous style for
+YARA rules.
+
+The `fmt` command—a powerful tool that helps standardize the look of your YARA
+rules—was introduced in YARA-X 0.8.0, but in version 0.9.0 it became
+customizable. This post will show you how to use this command, explore the
+options available, and guide you in creating your own configuration file for the
+best possible formatting experience.
+
+## Getting started with the configuration file
+
+The `fmt` command in YARA-X draws its formatting rules from a configuration file
+named `.yara-x.toml`. By default, YARA-X looks for this file in your home
+directory (`${HOME}/.yara-x.toml`). If the file doesn’t exist, YARA-X will use
+its built-in default settings. Let’s explore what you can do with a customized
+`.yara-x.toml` file.
+
+Here is an example configuration file:
+
+```toml
+# YARA-X Configuration File (.yara-x.toml)
+
+[fmt]
+
+# Indent section headers
+rule.indent_section_headers = true
+
+# Indent the contents within each section
+rule.indent_section_contents = true
+
+# Number of spaces used for indentation
+rule.indent_spaces = 2
+
+# Align metadata key-value pairs
+meta.align_values = false
+
+# Align pattern key-value pairs
+patterns.align_values = false
+```
+
+Let’s break down these settings, see what they do, and understand how they can
+help standardize your YARA rule formatting.
+
+### Indenting section headers and contents
+
+The `[fmt]` section in your `.yara-x.toml` file provides several settings to
+control indentation:
+
+`rule.indent_section_headers` determines whether section headers (
+like `meta:`, `strings:`, and `condition:`) should be indented within a YARA
+rule. If set to `true`, the headers will be indented with respect to the rule's
+body.
+
+Example (with indentation enabled):
+
+```yara
+rule example_rule {
+  meta:
+    description = "An example rule"
+
+  strings:
+    $a = "test"
+
+  condition:
+    $a
+}
+```
+
+Example (with indentation disabled):
+
+```yara
+rule example_rule {
+meta:
+  description = "An example rule"
+
+strings:
+  $a = "test"
+
+condition:
+  $a
+}
+```
+
+`rule.indent_section_contents` controls whether the contents within each section
+are further indented. For example, inside the `condition:` section, any
+conditions
+are indented relative to the section header. This setting can help make your
+rules more readable by visually distinguishing between headers and their
+corresponding content.
+
+Example (with indentation enabled):
+
+```yara
+rule example_rule {
+  meta:
+    description = "An example rule"
+
+  strings:
+    $a = "test"
+
+  condition:
+    $a
+}
+```
+
+Example (with indentation disabled):
+
+```yara
+rule example_rule {
+  meta:
+  description = "An example rule"
+
+  strings:
+  $a = "test"
+
+  condition:
+  $a
+}
+```
+
+### Choosing the number of spaces for indentation
+
+`rule.indent_spaces` specifies how many spaces are used for indentation. You
+can set it to any positive integer (common choices are 2 or 4 spaces). If you
+prefer to use tabs instead of spaces, simply set `rule.indent_spaces` to 0.
+
+### Aligning metadata and patterns
+
+`meta.align_values` controls whether the key-value pairs in the `meta:` section
+should be aligned. When set to `true`, the `=` signs for all metadata entries
+will be aligned, making it easier to read and compare information.
+
+Example (with alignment enabled):
+
+```yara
+rule example_rule {
+  meta:
+    author      = "Jane Doe"
+    description = "Detects example strings"
+}
+```
+
+Example (with alignment disabled):
+
+```yara
+rule example_rule {
+  meta:
+    author = "Jane Doe"
+    description = "Detects example strings"
+}
+```
+
+`patterns.align_values` is similar to `meta.align_values`, but his controls the
+alignment of key-value pairs in the `strings:` section of the rule.
+
+Example (with alignment enabled):
+
+```yara
+rule example_rule {
+  strings:
+    $short     = "abc"
+    $longer    = { 01 02 03 }
+    $very_long = /regex/
+}
+```
+
+Example (with alignment disabled):
+
+```yara
+rule example_rule {
+  strings:
+    $short = "abc"
+    $longer = { 01 02 03 }
+    $very_long = /regex/
+}
+```
+
+## Conclusion
+
+YARA-X’s `fmt` command, especially in its customizable form, is a game-changer
+for anyone working with YARA rules. It allows you to bring structure,
+readability, and consistency to your rules, making them easier to maintain and
+less error-prone.
+
+If you haven't yet tried out YARA-X’s `fmt` command, now is the perfect time to
+start. Consistency, after all, is key to effective collaboration and efficient
+threat hunting.

site/hugo_stats.json

@@ -42,6 +42,7 @@
       "module",
       "nav",
       "noscript",
+      "ol",
       "p",
       "path",
       "pre",
@@ -202,7 +203,6 @@
       "mt-n3",
       "mx-2",
       "mx-auto",
-      "mx-xl-auto",
       "my-3",
       "nav",
       "nav-item",
@@ -324,6 +324,7 @@
       "__init__relaxed_re_syntaxfalse",
       "absint",
       "add_sourcestring-originnone",
+      "aligning-metadata-and-patterns",
       "alphabets-for-base64-modifiers",
       "alternatives",
       "anonymous-patterns",
@@ -346,11 +347,15 @@
       "characteristics",
       "checksum32offset-size",
       "checksum32string",
+      "choosing",
+      "choosing-the-number-of-spaces-for-indentation",
       "class",
       "comments",
       "compile",
       "compileerror",
       "compiler",
+      "conclusion",
+      "configuration-options-for-the-fmt-command",
       "converting-ndjson-to-standard-json",
       "countbyte-offset-size",
       "countersignature",
@@ -431,6 +436,7 @@
       "function",
       "functions",
       "further-reading",
+      "getting-started-with-the-configuration-file",
       "global-rules",
       "go-api",
       "h-rh-i-0",
@@ -458,6 +464,8 @@
       "importstype-dll_name-fn_name",
       "in_rangetest-lower-upper",
       "incompatible-apis",
+      "indenting-section-headers-and-contents",
+      "indenting-section-headers-and-contents-1",
       "installation",
       "installing-with-cargo",
       "is-yara-really-dead",
@@ -585,6 +593,7 @@
       "the--character-must-be-escaped-in-regular-expressions",
       "the-bad-things",
       "the-good-things",
+      "the-power-of-fmt-in-yara-x",
       "the-with-statement",
       "timeouterror",
       "to_intstring",
@@ -606,7 +615,6 @@
       "wildcards",
       "xor-modifier",
       "xor_key",
-      "yara-x-config-guide",
       "yrx_compile",
       "yrx_compiler",
       "yrx_compiler_add_source",