ami-guide.txt

Programming with AMI
--------------------

AMI is a language designed to describe actions calling handlers with a set of functions
and variables.

Actions handlers can consume or create variables to be used by others after them.


2 minutes dive into AMI
=======================

Let's dive in the syntax now:

```
ami_version 1

action HelloWorld {
       $var = "Hello, world!"
       exec MyHandler
}
```

This example starts setting the mandatory ami_version, which must be 1 for now. Then
provides an action called "HelloWorld" which should execute a handler "MyHandler" with
the famous "Hello, world!" set to the $var variable.

Since Actions can be repeated, this example shows an action repeated 5 times:

```
ami_version 1

repeat 5 as $index {
       action HelloWorld {
       	      $var = "Hello, world!"
	      exec MyHandler
       }
}
```

The repeat keyword is self-explainatory, followed by the number of times it should
repeat, and defining a variable $index to hold the repeat iteration counter. It
can be used later to read a CSV sequentially etc.


Annotations
===========

In AMI, there are a few available annotations: revision, author, shortdesc, description, reference and tag.

 * revision: a simple number you manually increment and start with 1 when you first create a file. This
             is meant for understanding how many times someone worked on a given file.

 * author: the file author, to know who to ping when one has a question.

 * shortdesc: a short description about the AMI, usually a one-liner.

 * description: a longer description about the AMI, usually multi-lines.

 * reference: a link to what helped the author to build this AMI file. Can have as many references as needed.

 * tag: a tag which can help classify that particular file. Can have as many tags as needed.


Here's an example on how to use annotations:

```
ami_version 1
revision 1
author "Seb Tricaud <myemail@example.com>"

shortdesc "This is an example showing annotations"

reference "http://www.example.com"
reference "http://github.com/devoinc/pcraft"

tag "tlp:white"
tag "pcraft:annotation"
```

Functions
=========

Variables can be assigned from a function. AMI provides a bunch of functions.

base64.encode
-------------

Encode the "string" to base64:
```
base64.encode("string")
```

crypto.md5
----------

Hash using md5 the "string":
```
crypto.md5("string")
```

crypto.sha1
-----------

Hash using sha1 the "string":
```
crypto.sha1("string")
```

crypto.sha256
-------------

Hash using sha256 the "string":
```
crypto.sha256("string")
```

file.amidir
-----------

Prefixes the ami file dir to the file given as argument
```
csv(file.amidir("file.csv"), 3, "field", 1)
$filename = file.amidir("filename.pcap")
```

Will not take the file from the current dir, but from the dir where
the ami file is.

file.readall
------------

Read all content of the file "filename":
```
file.readall("filename")
```

uuid.v4
-------

Create a random UUID v4
```
uuid.v4("")
```

uuid.v5
-------

Create a UUID with "base string" that will always generate the same UUID.
```
uuid.v5("base string")
```

crypto.rc4
----------

Encrypt/Decrypt the "string" using the "key"
```
crypto.rc4("key", "string")
```

random.int
----------

Generate a random value between 10 and 42
```
random.int(10, 42)
```

csv
---

Read a "field" from the csv "file.csv" at line 5 with a header
```
csv("file.csv", 5, "field", has_header=true)
```

string.upper
------------

Convert the "string" to uppercase:
```
string.upper("string")
```

string.lower
------------

Convert the "string" to lowercase:
```
string.lower("string")
```

hostname_generator
------------------

Generate a consistent hostname from an ip address, such as "127.0.0.1":
```
hostname_generator("127.0.0.1")
```

Note that you can create an uppercase hostname by providing this function as an argument for string.upper, such as:
```
$uphost = string.upper(hostname_generator("127.0.0.1"))
```

Strings
=======

There are three types of strings in AMI:

  * A regular string, such as "my string" or "my \"string\"". It cannot have line return.
  * A Verbatim string, enclosed in three double-quotes: """my verbatim string""" which can contain line returns.
  * A Verbatim with substitutions string: prepend 's' to your verbatim string, and variables replacement will be done.

Examples
--------

```
$str = "Hello, World!"
$mystr = s"""This verbatim string
can have "${str}" as a string substitution
"""
$verbatim = """This string will not replace ${str} as it would with regular strings or substitute strings."""
```

Field operations
================

A field operation is to handle a specific field in a given action. None of the field actions are carried outside of the
actions themselves. This is a big difference with the variables.

As of now, there are two operations for a field: replacement and set.

Replacement
-----------

Replacement means we replace one value with another, on the wanted field. In this case, the "ip" field. This example shows how to replace two values on this specific field:
```
field["ip"].replace("127.0.0.1" => "192.168.0.32", "172.16.0.32" => "192.168.0.55")
```

Set
---

Set is only an assignment, however instead of being a variable that goes to the other actions, it is kept only in the context of the actual action.

```
field["ip"] = "127.0.0.1"
```

Sleep operation
===============

Sleep is an operation that can be done from anywhere, in second, whose value is a float.

For example, to sleep 1.5 seconds, one would write this:
```
sleep 1.5
```