github.com/niluplatform/go-nilu@v1.7.4-0.20200912082737-a0cb0776d52c/cmd/clef/rules.md (about)

     1  # Rules
     2  
     3  The `signer` binary contains a ruleset engine, implemented with [OttoVM](https://github.com/robertkrimen/otto)
     4  
     5  It enables usecases like the following:
     6  
     7  * I want to auto-approve transactions with contract `CasinoDapp`, with up to `0.05 ether` in value to maximum `1 ether` per 24h period
     8  * I want to auto-approve transaction to contract `EthAlarmClock` with `data`=`0xdeadbeef`, if `value=0`, `gas < 44k` and `gasPrice < 40Gwei`
     9  
    10  The two main features that are required for this to work well are;
    11  
    12  1. Rule Implementation: how to create, manage and interpret rules in a flexible but secure manner
    13  2. Credential managements and credentials; how to provide auto-unlock without exposing keys unnecessarily.
    14  
    15  The section below deals with both of them
    16  
    17  ## Rule Implementation
    18  
    19  A ruleset file is implemented as a `js` file. Under the hood, the ruleset-engine is a `SignerUI`, implementing the same methods as the `json-rpc` methods
    20  defined in the UI protocol. Example:
    21  
    22  ```javascript
    23  
    24  function asBig(str){
    25      if(str.slice(0,2) == "0x"){ return new BigNumber(str.slice(2),16)}
    26      return new BigNumber(str)
    27  }
    28  
    29  // Approve transactions to a certain contract if value is below a certain limit
    30  function ApproveTx(req){
    31  
    32      var limit = big.Newint("0xb1a2bc2ec50000")
    33  	var value = asBig(req.transaction.value);
    34  
    35  	if(req.transaction.to.toLowerCase()=="0xae967917c465db8578ca9024c205720b1a3651a9")
    36  	    && value.lt(limit) ){
    37  	    return "Approve"
    38  	 }
    39      // If we return "Reject", it will be rejected.
    40      // By not returning anything, it will be passed to the next UI, for manual processing
    41  }
    42  
    43  //Approve listings if request made from IPC
    44  function ApproveListing(req){
    45      if (req.metadata.scheme == "ipc"){ return "Approve"}
    46  }
    47  
    48  ```
    49  
    50  Whenever the external API is called (and the ruleset is enabled), the `signer` calls the UI, which is an instance of a ruleset-engine. The ruleset-engine
    51  invokes the corresponding method. In doing so, there are three possible outcomes:
    52  
    53  1. JS returns "Approve"
    54    * Auto-approve request
    55  2. JS returns "Reject"
    56    * Auto-reject request
    57  3. Error occurs, or something else is returned
    58    * Pass on to `next` ui: the regular UI channel.
    59  
    60  A more advanced example can be found below, "Example 1: ruleset for a rate-limited window", using `storage` to `Put` and `Get` `string`s by key.
    61  
    62  * At the time of writing, storage only exists as an ephemeral unencrypted implementation, to be used during testing.
    63  
    64  ### Things to note
    65  
    66  The Otto vm has a few [caveats](https://github.com/robertkrimen/otto):
    67  
    68  * "use strict" will parse, but does nothing.
    69  * The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification.
    70  * Otto targets ES5. ES6 features (eg: Typed Arrays) are not supported.
    71  
    72  Additionally, a few more have been added
    73  
    74  * The rule execution cannot load external javascript files.
    75  * The only preloaded libary is [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) version `2.0.3`. This one is fairly old, and is not aligned with the documentation at the github repository.
    76  * Each invocation is made in a fresh virtual machine. This means that you cannot store data in global variables between invocations. This is a deliberate choice -- if you want to store data, use the disk-backed `storage`, since rules should not rely on ephemeral data.
    77  * Javascript API parameters are _always_ an object. This is also a design choice, to ensure that parameters are accessed by _key_ and not by order. This is to prevent mistakes due to missing parameters or parameter changes.
    78  * The JS engine has access to `storage` and `console`.
    79  
    80  #### Security considerations
    81  
    82  ##### Security of ruleset
    83  
    84  Some security precautions can be made, such as:
    85  
    86  * Never load `ruleset.js` unless the file is `readonly` (`r-??-??-?`). If the user wishes to modify the ruleset, he must make it writeable and then set back to readonly.
    87    * This is to prevent attacks where files are dropped on the users disk.
    88  * Since we're going to have to have some form of secure storage (not defined in this section), we could also store the `sha3` of the `ruleset.js` file in there.
    89    * If the user wishes to modify the ruleset, he'd then have to perform e.g. `signer --attest /path/to/ruleset --credential <creds>`
    90  
    91  ##### Security of implementation
    92  
    93  The drawbacks of this very flexible solution is that the `signer` needs to contain a javascript engine. This is pretty simple to implement, since it's already
    94  implemented for `geth`. There are no known security vulnerabilities in, nor have we had any security-problems with it so far.
    95  
    96  The javascript engine would be an added attack surface; but if the validation of `rulesets` is made good (with hash-based attestation), the actual javascript cannot be considered
    97  an attack surface -- if an attacker can control the ruleset, a much simpler attack would be to implement an "always-approve" rule instead of exploiting the js vm. The only benefit
    98  to be gained from attacking the actual `signer` process from the `js` side would be if it could somehow extract cryptographic keys from memory.
    99  
   100  ##### Security in usability
   101  
   102  Javascript is flexible, but also easy to get wrong, especially when users assume that `js` can handle large integers natively. Typical errors
   103  include trying to multiply `gasCost` with `gas` without using `bigint`:s.
   104  
   105  It's unclear whether any other DSL could be more secure; since there's always the possibility of erroneously implementing a rule.
   106  
   107  
   108  ## Credential management
   109  
   110  The ability to auto-approve transaction means that the signer needs to have necessary credentials to decrypt keyfiles. These passwords are hereafter called `ksp` (keystore pass).
   111  
   112  ### Example implementation
   113  
   114  Upon startup of the signer, the signer is given a switch: `--seed <path/to/masterseed>`
   115  The `seed` contains a blob of bytes, which is the master seed for the `signer`.
   116  
   117  The `signer` uses the `seed` to:
   118  
   119  * Generate the `path` where the settings are stored.
   120    * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/vault.dat`
   121    * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/rules.js`
   122  * Generate the encryption password for `vault.dat`.
   123  
   124  The `vault.dat` would be an encrypted container storing the following information:
   125  
   126  * `ksp` entries
   127  * `sha256` hash of `rules.js`
   128  * Information about pair:ed callers (not yet specified)
   129  
   130  ### Security considerations
   131  
   132  This would leave it up to the user to ensure that the `path/to/masterseed` is handled in a secure way. It's difficult to get around this, although one could
   133  imagine leveraging OS-level keychains where supported. The setup is however in general similar to how ssh-keys are  stored in `.ssh/`.
   134  
   135  
   136  # Implementation status
   137  
   138  This is now implemented (with ephemeral non-encrypted storage for now, so not yet enabled).
   139  
   140  ## Example 1: ruleset for a rate-limited window
   141  
   142  
   143  ```javascript
   144  
   145  	function big(str){
   146  		if(str.slice(0,2) == "0x"){ return new BigNumber(str.slice(2),16)}
   147  		return new BigNumber(str)
   148  	}
   149  
   150  	// Time window: 1 week
   151  	var window = 1000* 3600*24*7;
   152  
   153  	// Limit : 1 ether
   154  	var limit = new BigNumber("1e18");
   155  
   156  	function isLimitOk(transaction){
   157  		var value = big(transaction.value)
   158  		// Start of our window function
   159  		var windowstart = new Date().getTime() - window;
   160  
   161  		var txs = [];
   162  		var stored = storage.Get('txs');
   163  
   164  		if(stored != ""){
   165  			txs = JSON.parse(stored)
   166  		}
   167  		// First, remove all that have passed out of the time-window
   168  		var newtxs = txs.filter(function(tx){return tx.tstamp > windowstart});
   169  		console.log(txs, newtxs.length);
   170  
   171  		// Secondly, aggregate the current sum
   172  		sum = new BigNumber(0)
   173  
   174  		sum = newtxs.reduce(function(agg, tx){ return big(tx.value).plus(agg)}, sum);
   175  		console.log("ApproveTx > Sum so far", sum);
   176  		console.log("ApproveTx > Requested", value.toNumber());
   177  
   178  		// Would we exceed weekly limit ?
   179  		return sum.plus(value).lt(limit)
   180  
   181  	}
   182  	function ApproveTx(r){
   183  		if (isLimitOk(r.transaction)){
   184  			return "Approve"
   185  		}
   186  		return "Nope"
   187  	}
   188  
   189  	/**
   190  	* OnApprovedTx(str) is called when a transaction has been approved and signed. The parameter
   191   	* 'response_str' contains the return value that will be sent to the external caller.
   192  	* The return value from this method is ignore - the reason for having this callback is to allow the
   193  	* ruleset to keep track of approved transactions.
   194  	*
   195  	* When implementing rate-limited rules, this callback should be used.
   196  	* If a rule responds with neither 'Approve' nor 'Reject' - the tx goes to manual processing. If the user
   197  	* then accepts the transaction, this method will be called.
   198  	*
   199  	* TLDR; Use this method to keep track of signed transactions, instead of using the data in ApproveTx.
   200  	*/
   201   	function OnApprovedTx(resp){
   202  		var value = big(resp.tx.value)
   203  		var txs = []
   204  		// Load stored transactions
   205  		var stored = storage.Get('txs');
   206  		if(stored != ""){
   207  			txs = JSON.parse(stored)
   208  		}
   209  		// Add this to the storage
   210  		txs.push({tstamp: new Date().getTime(), value: value});
   211  		storage.Put("txs", JSON.stringify(txs));
   212  	}
   213  
   214  ```
   215  
   216  ## Example 2: allow destination
   217  
   218  ```javascript
   219  
   220  	function ApproveTx(r){
   221  		if(r.transaction.from.toLowerCase()=="0x0000000000000000000000000000000000001337"){ return "Approve"}
   222  		if(r.transaction.from.toLowerCase()=="0x000000000000000000000000000000000000dead"){ return "Reject"}
   223  		// Otherwise goes to manual processing
   224  	}
   225  
   226  ```
   227  
   228  ## Example 3: Allow listing
   229  
   230  ```javascript
   231  
   232      function ApproveListing(){
   233          return "Approve"
   234      }
   235  
   236  ```