Documentation notes and questions

[nkakouros]

Here are some typos I noticed:

https://github.com/mal-lang/mal-documentation/wiki/MAL-Code-Examples

• Association : 1-* -> 1..*
• Designates the all associated assets foo, then, the assets or elements bar. -> Designates all the associated assets foo, then, the assets or elements bar. Also, isn't bar an attack step here?

Also, some lines are two long and hard to read, perhaps they could be broken.

https://github.com/mal-lang/mal-documentation/wiki/MAL-Syntax :

• The multiplicity of a composite association can be [1], [1..*] or [*] on the composite end -> [0..1], [0..*], [1], [1..*], [*]
• An OR attack step A can be reached if any of the attack steps which refers to A is reached. -> which refers
• Hanging transition are allowed for let expression, e.g., let allFolders = folders.subFolder*. -> Hanging transitions are allowed for let expression, e.g., let allFolders = folders.subFolder*.
• TTC is a probability distribution reflects an attacker's ability of compromising an asset. -> TTC is a probability distribution that reflects an attacker's ability of compromising an asset.
• '<\type> nameHere @tag [ProbabilityDistribution(params)]' ->

`'<type> nameHere @tag [ProbabilityDistribution(params)]'`

• Comments in MAL files can be introduced by "//" -> Comments in MAL files can be introduced by //for single line or inline comments or with/* ... */for block comments. The//` can be inline, i.e. following some code in the same line, right?

https://github.com/mal-lang/mal-documentation/wiki/Metod-of-Creating-a-MAL

• Metod of Creating a MAL -> Method of creating a MAL specification

---

Some questions:

• If I understand correctly, each asset is comprised of attack steps. The step is not defined in the documentation, except implicitly when explaining the &, | operators.

• elements are referenced in various places. What is an element?

• From the docs, an association is defined as:

<id> [<id>] <mult> <-- <id> --> <mult> [<id>] <id>

But category names are also defined as id both here and here. Are categories accepted into associations and if yes how would that work?

• In the exampleLang example, there is this snippet:

  asset Host {
    | connect
      -> access
    | authenticate
      -> access
    | guessPassword
      -> guessedPassword
    | guessedPassword [Exponential(0.02)]
      -> authenticate
    & access
  }

This implies that to get access all 4 previous attack steps need to take place. But this is not the case in reality. How does MAL deal with such cases where the boolean logic leading to a step is not a simple AND or OR? Is it up to the designer to introduce intermediary steps, perhaps using @hidden steps?

• For the # defence symbol, the docs say:

As opposed to attack steps defenses are boolean. While declaring an asset, it is possible to either enable or disable a defense step by setting the defense step to either TRUE or FALSE. It is also possible to assign a Bernoulli distribution to govern the activation.

There is no example of how you turn the defence on/off or how you assign a distribution. Also, attack steps are also boolean in the sense that they are AND/OR steps.

• About existence checks, do they support the AND boolean logic? How? Maybe with multiple <-s?

• Does the ordering of attack steps matter with regard to the business logic? Does it matter for the compiler (perhaps there is a chance of producing undefined labels). Where is the start?

• Can I use the <- operator to specify the attack steps that are required for another attack step? E.g.

| finalStep
<- requiredPreviousStep

• Regarding unions/intersections there are these two examples:

  -> computers[WindowsMachine] \/ computers[LinuxMachine]
// all associated Windows and Linux machines

  -> computers.operatingSystems[Windows] /\ computers.operatingSystems[Linux]
// the set of associated computers which has both Windows and Linux installed

I understand the first example. The second seems wrong. The collect operator is used to denote what seems like a property of computers and not an attack step. If this is permitted, it is not documented.

Also, the explanation in the union is a bit weird. Is the intersection really the set of dual boot computers? This implies that two assets can refer to the same entity. Is this permitted? If yes, it would be a good idea to include this info in the docs and the explanation of the union operator could be improved as: all machines running Windows, Linux or both.

• The , operator is not included in the table.

• There is no explanation for TTC distributions, only this example in the top of the page:

category Security {
    asset Firewall {
        & bypass [Bernoulli(0.2)]
            -> computer.firewallBypassed
        # hardened
            -> bypass
    }
}

One thing I would like to know, can I use let expressions as an argument (inside the parentheses) to distribution functions?

• The docs say:

Inline documentation using the three info elements is preferred over other formats.

What other formats are there? Comments?