Code review general refactoring

src/main/mal/IAM.mal

@@ -19,17 +19,18 @@ category IAM {
     abstract asset IAMObject extends Information
       user info: "An IAM object represents the base logic shared by all assets used for Identity and Access Management roles(Identity, Group, Privileges)."
     {
-      # disabled [Disabled]
-        user info: "It should be used to model the probability that the IAM object does not actually exist."
+      # notPresent [Disabled]
+        user info: "This defense is used to reason about the attack vectors introduced by this asset. It should be used to model the possibility that the IAM object does not actually exist."
+        developer info: "Enabling this defense should make the asset behave as if it did not exist, as such all of its impactful attack steps should be disabled by it."
         ->  successfulAssume,
             successfulLockout
 
-      | attemptAssume
-        user info: "Attempt to assume the privileges associated with the IAM object. If disabled this will not be possible."
+      | attemptAssume @hidden
+        developer info: "Intermediate attack step to allow for defenses."
         ->  successfulAssume
 
       & successfulAssume @hidden
-        developer info: "Intermediate attack step to model the requirements for the assume attack step."
+        developer info: "Intermediate attack step to model defenses."
         ->  assume
 
       | assume
@@ -52,11 +53,11 @@ category IAM {
         +>  attemptAssume
 
       | attemptLockout @hidden
-        developer info: "Intermediate attack step."
+        developer info: "Intermediate attack step to allow for defenses."
         ->  successfulLockout
 
       & successfulLockout @hidden
-        developer info: "Intermediate attack step to model defences."
+        developer info: "Intermediate attack step to model defenses."
         ->  lockout
 
       | lockout {A}
@@ -70,22 +71,15 @@ category IAM {
       user info: "An identity models an IAM identity that should then be associated with privileges on other instances."
       developer info: "An identity can be visualised as a group of assumable roles that can be associated with many credentials."
     {
-      # disabled
-        +>  successfulLockoutFromCredentials
-
       | assume @Override {C,I,A}
         user info: "After authentication or compromise of an account/identity, assume its privileges."
         developer info: "This is both legitimate and illegitimate access! Also assume all the privileges of the parent identities (on the above level/inherited by this identity) because those represent the group of (inherited) roles."
         +>  parentId.attemptAssume,
             memberOf.attemptAssume
 
-      & attemptLockoutFromCredentials @hidden
+      & lockoutFromCredentials @hidden
         developer info: "Only lockout an identity if all of the Credentials that could be used to authenticate have been denied."
-        ->  successfulLockoutFromCredentials
-
-      & successfulLockoutFromCredentials @hidden
-        developer info: "Intermediate attack step to model defences."
-        ->  lockout
+        ->  attemptLockout
 
       | lockout
         user info: "If all of the Identities belonging to a Group are lockedout we assume that the Group as a whole is lockedout."
@@ -98,26 +92,26 @@ category IAM {
     }
 
     asset Privileges extends IAMObject
-      user info: "A privileges asset can be associated with an identity to group a set of given privileges on Applications and Data."
-      modeller info: "The privileges asset is not meant to be used normally when assigning permissions. Identities and Groups should be directly connected to the relevant assets. The purpose of the Privileges asset is to be used as a speculative asset when reasoning about additional privileges that a particular Group or Identity may have as a result of either poor configurations or the attacker's actions."
+      user info: "A privileges asset can be associated with another IAMObject to reason about a specific subset of given privileges on Applications and Data."
+      modeler info: "The privileges asset is not meant to be used normally when assigning permissions. Identities and Groups should be directly associated with the relevant assets. The purpose of the Privileges asset is to be used as a speculative asset when reasoning about additional privileges that a particular Group or Identity may have as a result of either poor configurations or the attacker's actions."
     {
       | assume @Override {C,I,A}
-        user info: "After authentication or compromise of an account/identity, assume its privileges."
+        user info: "After authentication or compromise assume its privileges."
         developer info: "Assume identity/group the privileges are associated with since the privileges are simply an extension of it."
         +>  IAMOwners.attemptAssume
     }
 
     asset Group extends IAMObject
-      user info: "A group is a way to group together identities and/or groups. This allows the expression of hierarchical IAM (structured inheritance)."
+      user info: "A group is a way to group together identities and/or other groups. This allows the expression of hierarchical IAM (structured inheritance)."
       modeler info: "Groups can be used instead of nested identities to make the model more intuitive and clearer to understand."
     {
       | assume @Override {C,I,A}
-        user info: "If an identity of a group is compromised then the whole group (i.e. all other privileges of the group) should be considered as compromised. Furthermore, the parent groups should also be considered compromised."
+        user info: "If an identity of a group is compromised then the whole group(i.e. all other privileges of the group) should be considered as compromised. Furthermore, the parent groups should also be considered compromised."
         developer info: "The parent groups should be compromised because all the privileges of the parent groups are inherited on the children groups but lower children groups should not be compromised because lower levels might have inherited plus additional privileges."
         +>  parentGroup.attemptAssume
 
       & lockoutFromMembers @hidden
-        user info: "If all of the Identities belonging to a Group are lockedout we assume that the Group as a whole is lockedout."
+        developer info: "If all of the Identities belonging to a Group are lockedout we assume that the Group as a whole is lockedout."
         ->  lockout
     }
 
@@ -130,7 +124,7 @@ category IAM {
         ->  useLeakedCredentials
 
       # notGuessable [Enabled]
-        user info: "Describes if the credentials can be guessed by the attacker(e. g. they represent a password or passphrase)."
+        user info: "Describes if the credentials can be guessed by the attacker(i.e. they represent a password or passphrase)."
         ->  guessCredentials
 
       # unique [Enabled]
@@ -139,76 +133,68 @@ category IAM {
             propagateOneCredentialCompromised
 
       # notPhishable [Disabled]
-        user info: "Describes if the credentials cannot be phished(they are biometric, e. g. fingerprints or iris scans, or physical, e. g. access cards or keys, elements)."
+        user info: "Describes if the credentials cannot be phished(they are biometric, e.g. fingerprints or iris scans, or physical, e.g. access cards or keys, elements)."
         ->  credentialTheft
 
       | read @Override
-        developer info: "If the attacker is able to read the information containing credentials we assume that they are compromised."
-        +> attemptUse
+        user info: "If the attacker is able to read the information containing credentials we assume that they are compromised."
+        +> use
 
       | write @Override
-        developer info: "If the attacker is able to write the information containing credentials we assume that they have changed them for the authentication process."
-        +> attemptUse
+        user info: "If the attacker is able to write the information containing credentials we assume that they have changed them for the authentication process."
+        +> use
 
       | deny @Override
-        developer info: "If the attacker is able to deny the information containing credentials we assume that they have denied them for the authentication process."
-        +> identities.attemptLockoutFromCredentials
+        user info: "If the attacker is able to deny the information containing credentials we assume that they have denied them for the authentication process."
+        +> identities.lockoutFromCredentials
 
       | useLeakedCredentials [EasyAndCertain]
         user info: "If the password/credential is leaked to some location, it can then be available to the attacker and therefore it can be used."
-        ->  attemptUse
+        ->  use
 
       | attemptCredentialsReuse @hidden
-        developer info: "Intermediate step used to trigger the reuse attack step on other credentials belonging to the same user."
+        developer info: "Intermediate attack step to allow for defenses."
         ->  credentialsReuse,
             requiredFactors.attemptCredentialsReuse
 
-      & credentialsReuse
+      & credentialsReuse @hidden
         developer info: "The user is reusing credentials which means that the attacker is able to compromise all of the non-unique credentials associated with this user."
-        ->  attemptUse
-
-      | attemptUse
-        user info: "The attacker is using the credentials to perform a legitimate authentication."
         ->  use
 
-      & use {C}
+      | use {C}
         user info: "The attacker is using the credentials to perform a legitimate authentication."
         ->  identities.attemptAssume,
             encryptedData.accessDecryptedData,
             signedData.accessSpoofedData,
             attemptPropagateOneCredentialCompromised,
             credentials.use,
-            hashes.attemptUse,
+            hashes.use,
             origCreds.guessCredentialsFromHash
 
       | attemptPropagateOneCredentialCompromised @hidden
-        developer info: "Intermediate step used to propagate the credentials reuse attack step."
+        developer info: "Intermediate attack step to allow for defenses."
         ->  propagateOneCredentialCompromised
 
       & propagateOneCredentialCompromised @hidden
         developer info: "Intermediate step used to propagate the credentials reuse attack step."
         ->  credentials*.identities.users.oneCredentialCompromised
 
-      | attemptAccess
-        user info: "The attacker is attempting to access the credentials."
-        ->  attemptUse
-
       | attemptCredentialTheft @hidden
-        developer info: "Intermediate step used to trigger the credential theft attack step."
+        developer info: "The attacker is attempting to access the credentials."
         ->  credentialTheft,
             requiredFactors.attemptCredentialTheft
 
-      & credentialTheft
-        user info: "The attacker is able to steal the credentials."
-        ->  attemptUse
+      & credentialTheft @hidden
+        developer info: "The attacker is able to steal the credentials."
+        ->  use
 
       !E missingIdentity @hidden
         developer info: "If there are no Identities asociated with these Credentials we make the worst case scenario assumption regarding the strength of the Credentials."
         <-  identities
         ->  weakCredentials
 
       | weakCredentials @hidden
-        developer info: "Intermediate step used to represent how weak the credentials the user employs are. This is inversely related to the securityAwareness defence on the User asset associated with the Identity to which these Credentials belong. If either the User or Identity associations are missing the assumption is made that the crentials are weak and therefore guessable by the attacker."
+        developer info: "Intermediate step used to represent how weak the credentials the user employs are. This is inversely related to the securityAwareness defense on the User asset associated with the Identity to which these Credentials belong. If either the User or Identity associations are missing the assumption is made that the crentials are weak and therefore guessable by the attacker."
         ->  guessCredentials,
             requiredFactors.weakCredentials
 
@@ -221,11 +207,10 @@ category IAM {
         developer info: "If hashes are associated with this Credentials asset the assumption is that one of those hashes is required by the attacker to be able to perform a guessing attack."
         ->  guessCredentials
 
-      & guessCredentials [HardAndUncertain]
-        user info: "The attacker can attempt to just guess a set of credentials. The likelihood of succeeding is depend on how strong the credentials are."
-        modeller info: "The guessability of the Credentials is influenced by the notGuessable defence on this asset and the securityAwareness defence on the User associated with the Identity that these Credentials belong to. If either the User or Identity associations are missing the assumption is made that the crentials are guessable and only the notGuessable defence would play a role in restricting this attack step."
-        developer info: "We should research the probability we want to use for this attack step more."
-        ->  attemptUse
+      & guessCredentials @hidden [HardAndUncertain]
+        developer info: "The attacker can try to just guess a set of credentials. The likelihood of succeeding is dependent on how strong the credentials are."
+        modeler info: "The guessability of the Credentials is influenced by the notGuessable defense on this asset and the securityAwareness defense on the User associated with the Identity that these Credentials belong to. If either the User or Identity associations are missing the assumption is made that the crentials are guessable and only the notGuessable defense would play a role in restricting this attack step."
+        ->  use
     }
 }