Skip to content

Commit

Permalink
doc: more improvements to documentation site.
Browse files Browse the repository at this point in the history
  • Loading branch information
@plusvic
plusvic committed May 3, 2024
1 parent 1173d24 commit f297bc9
Show file tree
Hide file tree
Showing 8 changed files with 564 additions and 383 deletions.
Binary file added site/content/docs/intro/duplicate_rule_error.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/content/docs/intro/wrong_arguments_error.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
59 changes: 59 additions & 0 deletions site/content/docs/intro/yara_vs_yara-x.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: "YARA-X vs YARA"
description: "How YARA-X and YARA differ. Which are the pros and cons."
summary: ""
date: 2023-09-07T16:04:48+02:00
lastmod: 2023-09-07T16:04:48+02:00
draft: false
menu:
docs:
parent: ""
identifier: "yara-x_vs_yara"
weight: 115
toc: true
seo:
title: "" # custom title (optional)
description: "" # custom description (recommended)
canonical: "" # custom canonical URL (optional)
noindex: false # false (default) or true
---

YARA-X intends to be the replacement for YARA, and it has been designed with
usability, backward-compatibility, and performance in mind. YARA-X is already
better than YARA in many aspects, but it's still very young and therefore some
features are not implemented yet, and there are rough edges that need to be
polished. This section covers the pros and cons of YARA-X versus YARA.

## The good things

Let's start by talking about the things that YARA-X does better. If you prefer
seeing the glass half-empty go to [the bad things](#the-bad-things) section.

### Better error reporting

Error reports in YARA-X are much more detailed and explicative. Each error
message tries to provide as much context about the error as possible, which
improves the user's experience. They also look better.

![duplicate_rule_error.png](duplicate_rule_error.png)

![wrong_arguments_error.png](wrong_arguments_error.png)

### More user friendly CLI

### Higher overall performance

### Parser reusability

## The bad things

Of course, not everything is great. YARA-X has some drawbacks that we need to
discuss too. Some of the drawbacks are related to the lack of features that
YARA already has, but YARA-X does not. These may be eliminated in the future as
YARA-X matures.

### API is not compatible

### No include statements

### No process scanning
108 changes: 54 additions & 54 deletions site/content/docs/modules/dotnet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,32 +45,32 @@ rule BlopStream {

## Module structure

| Field | Type |
|------------------------------|--------------------------------------|
| is_dotnet | bool |
| module_name | string |
| version | string |
| number_of_streams | integer |
| number_of_guids | integer |
| number_of_resources | integer |
| number_of_generic_parameters | integer |
| number_of_classes | integer |
| number_of_assembly_refs | integer |
| number_of_modulerefs | integer |
| number_of_user_strings | integer |
| number_of_constants | integer |
| number_of_field_offsets | integer |
| typelib | string |
| streams | array of [Stream](#stream) |
| guids | array of string |
| constants | array of string |
| assembly | [Assembly](#assembly) |
| assembly_refs | array of [AssemblyRef](#assemblyref) |
| resources | array of [Resource](#resource) |
| classes | array of [Class](#class) |
| field_offsets | array of integer |
| user_strings | array of string |
| modulerefs | array of string |
| Field | Type |
|------------------------------|-----------------------------------|
| is_dotnet | bool |
| module_name | string |
| version | string |
| number_of_streams | integer |
| number_of_guids | integer |
| number_of_resources | integer |
| number_of_generic_parameters | integer |
| number_of_classes | integer |
| number_of_assembly_refs | integer |
| number_of_modulerefs | integer |
| number_of_user_strings | integer |
| number_of_constants | integer |
| number_of_field_offsets | integer |
| typelib | string |
| streams | [Stream](#stream) array |
| guids | string array |
| constants | string array |
| assembly | [Assembly](#assembly) array |
| assembly_refs | [AssemblyRef](#assemblyref) array |
| resources | [Resource](#resource) array |
| classes | [Class](#class) array |
| field_offsets | integer array |
| user_strings | string array |
| modulerefs | string array |

### Assembly

Expand Down Expand Up @@ -122,21 +122,21 @@ rule WindowsFirewallHelper {

This is the structure of each item in the `classes` array.

| Field | Type |
|------------------------------|----------------------------|
| fullname | string |
| name | string |
| namespace | string |
| visibility | string |
| type | string |
| abstract | bool |
| sealed | bool |
| number_of_base_types | integer |
| number_of_generic_parameters | integer |
| number_of_methods | integer |
| base_types | array of string |
| generic_parameters | array of string |
| methods | array of [Method](#method) |
| Field | Type |
|------------------------------|-------------------------|
| fullname | string |
| name | string |
| namespace | string |
| visibility | string |
| type | string |
| abstract | bool |
| sealed | bool |
| number_of_base_types | integer |
| number_of_generic_parameters | integer |
| number_of_methods | integer |
| base_types | string array |
| generic_parameters | string array |
| methods | [Method](#method) array |

###### Example

Expand All @@ -155,19 +155,19 @@ rule DebugInfoInPDBAttribute {

This is the structure of each item in the `methods` array within each Class.

| Field | Type |
|------------------------------|--------------------------|
| name | string |
| visibility | string |
| abstract | bool |
| static | bool |
| virtual | bool |
| final | bool |
| return_type | string |
| number_of_generic_parameters | integer |
| number_of_parameters | integer |
| generic_parameters | array of string |
| parameters | array of [Param](#param) |
| Field | Type |
|------------------------------|-----------------------|
| name | string |
| visibility | string |
| abstract | bool |
| static | bool |
| virtual | bool |
| final | bool |
| return_type | string |
| number_of_generic_parameters | integer |
| number_of_parameters | integer |
| generic_parameters | string array |
| parameters | [Param](#param) array |

###### Example

Expand Down
67 changes: 48 additions & 19 deletions site/content/docs/modules/elf.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,27 +37,56 @@ rule elf_64 {
}
```

## Functions

### import_md5()

Returns the MD5 of the import table.

### telfhash()

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
visit [https://github.com/trendmicro/telfhash](https://github.com/trendmicro/telfhash)
for tools other tools that compute the `telfhash`.

###### Example

```
import "elf"
rule FindByTelfhash {
condition:
elf.telfhash() == "t166a00284751084526486df8b5df5b2fccb3f511dbc188c37156f5e714a11bc5d71014d"
}
```

## Module structure

| Field | Type |
|-------------------------|------------------------------|
| type | [Type](#type) |
| machine | [Machine](#machine) |
| entry_point | integer |
| sh_offset | integer |
| sh_entry_size | integer |
| ph_offset | integer |
| ph_entry_size | integer |
| number_of_sections | integer |
| number_of_segments | integer |
| symtab_entries | integer |
| dynsym_entries | integer |
| dynamic_section_entries | integer |
| sections | array of [Section](#section) |
| segments | array of [Segment](#segment) |
| symtab | array of [Sym](#sym) |
| dynsym | array of [Sym](#sym) |
| dynamic | array of [Dyn](#dyn) |
| Field | Type |
|-------------------------|---------------------------|
| type | [Type](#type) |
| machine | [Machine](#machine) |
| entry_point | integer |
| sh_offset | integer |
| sh_entry_size | integer |
| ph_offset | integer |
| ph_entry_size | integer |
| number_of_sections | integer |
| number_of_segments | integer |
| symtab_entries | integer |
| dynsym_entries | integer |
| dynamic_section_entries | integer |
| sections | [Section](#section) array |
| segments | [Segment](#segment) array |
| symtab | [Sym](#sym) array |
| dynsym | [Sym](#sym) array |
| dynamic | [Dyn](#dyn) array |

### Dyn

Expand Down
80 changes: 40 additions & 40 deletions site/content/docs/modules/macho.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,19 @@ most of the fields present in a Mach-O file header. Let's see some examples:
| symtab | [Symtab](#symtab) |
| dysymtab | [Dysymtab](#dysymtab) |
| code_signature_data | [LinkedItData](#linkeditdata) |
| segments | array of [Segment](#segment) |
| dylibs | array of [Dylib](#dylib) |
| segments | [Segment](#segment) array |
| dylibs | [Dylib](#dylib) array |
| dyld_info | [DyldInfo](#dyldinfo) |
| rpaths | array of string |
| entitlements | array of string |
| rpaths | string array |
| entitlements | string array |
| certificates | [Certificates](#certificates) |
| uuid | string |
| build_version | [BuildVersion](#buildversion) |
| min_version | [MinVersion](#minversion) |
| fat_magic | integer |
| nfat_arch | integer |
| fat_arch | array of [FatArch](#fatarch) |
| file | array of [File](#file) |
| fat_arch | [FatArch](#fatarch) array |
| file | [File](#file) array |

### BuildTool

Expand All @@ -65,22 +65,22 @@ most of the fields present in a Mach-O file header. Let's see some examples:

### BuildVersion

| Field | Type |
|----------|----------------------------------|
| platform | integer |
| minos | string |
| sdk | string |
| ntools | integer |
| tools | array of [BuildTool](#buildtool) |
| Field | Type |
|----------|-------------------------------|
| platform | integer |
| minos | string |
| sdk | string |
| ntools | integer |
| tools | [BuildTool](#buildtool) array |

<a name="macho-Certificates"></a>

### Certificates

| Field | Type |
|--------------|-----------------|
| common_names | array of string |
| signer_names | array of string |
| Field | Type |
|--------------|--------------|
| common_names | string array |
| signer_names | string array |

### DyldInfo

Expand Down Expand Up @@ -157,10 +157,10 @@ most of the fields present in a Mach-O file header. Let's see some examples:
| entry_point | integer |
| stack_size | integer |
| source_version | string |
| segments | array of [Segment](#segment) |
| dylibs | array of [Dylib](#dylib) |
| rpaths | array of string |
| entitlements | array of string |
| segments | [Segment](#segment) array |
| dylibs | [Dylib](#dylib) array |
| rpaths | string array |
| entitlements | string array |
| symtab | [Symtab](#symtab) |
| dysymtab | [Dysymtab](#dysymtab) |
| dyld_info | [DyldInfo](#dyldInfo) |
Expand Down Expand Up @@ -204,28 +204,28 @@ most of the fields present in a Mach-O file header. Let's see some examples:

### Segment

| Field | Type |
|----------|------------------------------|
| segname | string |
| vmaddr | integer |
| vmsize | integer |
| fileoff | integer |
| filesize | integer |
| maxprot | integer |
| initprot | integer |
| nsects | integer |
| flags | integer |
| sections | array of [Section](#section) |
| Field | Type |
|----------|---------------------------|
| segname | string |
| vmaddr | integer |
| vmsize | integer |
| fileoff | integer |
| filesize | integer |
| maxprot | integer |
| initprot | integer |
| nsects | integer |
| flags | integer |
| sections | [Section](#section) array |

### Symtab

| Field | Type |
|---------|-----------------|
| symoff | integer |
| nsyms | integer |
| stroff | integer |
| strsize | integer |
| entries | array of string |
| Field | Type |
|---------|--------------|
| symoff | integer |
| nsyms | integer |
| stroff | integer |
| strsize | integer |
| entries | string array |

### CPU_ARM_64_SUBTYPE

Expand Down
Loading

0 comments on commit f297bc9

Please sign in to comment.