ListActions

ListActions will return a list of actions that have been performed on the node. The actions that will be persisted depends on the value of the --firewall.request-logger.level config option. The default value of the option is the "interceptor" mode which will persist only the actions (with all request parameters) made with macaroons with caveats that force them to be checked by an rpc middleware interceptor. If the "all" mode is used then all actions will be persisted but only full request parameters will only be stored if the actions are interceptor actions, otherwise only the URI and timestamp of the actions will be stored. The "full" mode will persist all request data for all actions.

Source: firewall.proto

gRPC

rpc ListActions (ListActionsRequest) returns (ListActionsResponse);

REST

HTTP Method	Path
POST	/v1/firewall/actions

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
const TLS_PATH = 'LIT_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('firewall.proto', loaderOptions);
const litrpc = grpc.loadPackageDefinition(packageDefinition).litrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new litrpc.Firewall(GRPC_HOST, creds);
let request = {
  feature_name: <string>,
  actor_name: <string>,
  method_name: <string>,
  state: <ActionState>,
  index_offset: <uint64>,
  max_num_actions: <uint64>,
  reversed: <bool>,
  count_total: <bool>,
  session_id: <bytes>,
  start_timestamp: <uint64>,
  end_timestamp: <uint64>,
  group_id: <bytes>,
};
client.listActions(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "actions": <Action>,
//    "last_index_offset": <uint64>,
//    "total_count": <uint64>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the firewall.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import firewall_pb2 as litrpc, firewall_pb2_grpc as firewallstub

GRPC_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = firewallstub.FirewallStub(channel)
request = litrpc.ListActionsRequest(
  feature_name=<string>,
  actor_name=<string>,
  method_name=<string>,
  state=<ActionState>,
  index_offset=<uint64>,
  max_num_actions=<uint64>,
  reversed=<bool>,
  count_total=<bool>,
  session_id=<bytes>,
  start_timestamp=<uint64>,
  end_timestamp=<uint64>,
  group_id=<bytes>,
)
response = stub.ListActions(request)
print(response)
# {
#    "actions": <Action>,
#    "last_index_offset": <uint64>,
#    "total_count": <uint64>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'

let requestBody = {
  feature_name: <string>, // <string> 
  actor_name: <string>, // <string> 
  method_name: <string>, // <string> 
  state: <string>, // <ActionState> 
  index_offset: <string>, // <uint64> 
  max_num_actions: <string>, // <uint64> 
  reversed: <boolean>, // <bool> 
  count_total: <boolean>, // <bool> 
  session_id: <string>, // <bytes> (base64 encoded)
  start_timestamp: <string>, // <uint64> 
  end_timestamp: <string>, // <uint64> 
  group_id: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/firewall/actions`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "actions": <array>, // <Action> 
//    "last_index_offset": <string>, // <uint64> 
//    "total_count": <string>, // <uint64> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/firewall/actions'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'feature_name': <string>,
  'actor_name': <string>,
  'method_name': <string>,
  'state': <ActionState>,
  'index_offset': <uint64>,
  'max_num_actions': <uint64>,
  'reversed': <bool>,
  'count_total': <bool>,
  'session_id': base64.b64encode(<bytes>),
  'start_timestamp': <uint64>,
  'end_timestamp': <uint64>,
  'group_id': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "actions": <Action>,
#    "last_index_offset": <uint64>,
#    "total_count": <uint64>,
# }

Shell

$ litcli actions --help

NAME:
   litcli actions - List actions performed on the Litd server

USAGE:
   litcli actions [command options] [arguments...]

CATEGORY:
   Firewall

OPTIONS:
   --feature value          The name of the feature to filter the actions by. If left empty, then all actions will be returned.
   --actor value            The actor name to filter the actions by. If left empty, then all actions will be returned.
   --method value           The method name to filter the actions by. If left empty, then all actions will be returned.
   --session_id value       The hex encoded session ID to filter the actions by. If left empty, then all actions will be returned.
   --start_timestamp value  Only actions executed after this unix timestamp will be considered. (default: 0)
   --end_timestamp value    Only actions executed before this unix timestamp will be considered. (default: 0)
   --state value            The action state to filter on. If not set, then actions of any state will be returned. Options include: 'pending', 'done' and 'error'.
   --index_offset value     The index of an action that will be used as the start of a query to determine which actions should be returned in the response. (default: 0)
   --max_num_actions value  The max number of actions to return. (default: 0)
   --oldest_first           If set, actions succeeding the index_offset will be returned.
   --count_total            Set to true if the total number of all actions that match the given filters should be counted and returned in the request. Note that setting this will significantly decrease the performance of the query if there are many actions in the db. Also note that if this option is set, the index_offset is the index in this set of actions where as if it is not set, then index_offset is the index of the action in the db regardless of filter.
   --group_id session_id    The hex encoded group ID to filter the actions by. The group ID is the same for all sessions that have been linked. If a session has no linked sessions then the group ID will be the same as the session ID. This flag will be ignored if the session_id flag is set.
   

Messages

litrpc.ListActionsRequest

Source: firewall.proto

Field	gRPC Type	REST Type	REST Placement
feature_name The feature name which the filter the actions by. If left empty, all feature actions will be returned.	string	string	body
actor_name The actor name to filter on. If left empty, all actor actions will be returned.	string	string	body
method_name The method name to filter on. If left empty, actions for any method will be returned.	string	string	body
state The action state to filter on. If set to zero, actions for any state will be returned.	ActionState	string	body
index_offset The index of an action that will be used as the start of a query to determine which actions should be returned in the response.	uint64	string	body
max_num_actions The max number of actions to return in the response to this query.	uint64	string	body
reversed If set, the actions returned will result from seeking backwards from the specified index offset. This can be used to paginate backwards.	bool	boolean	body
count_total Set to true if the total number of all actions that match the given filters should be counted and returned in the request. Note that setting this will significantly decrease the performance of the query if there are many actions in the db.	bool	boolean	body
session_id The session ID to filter on. If left empty, actions for any session will be returned.	bytes	string	body
start_timestamp If specified, then only actions created after the given timestamp will be considered.	uint64	string	body
end_timestamp If specified, then only actions created before the given timestamp will be considered.	uint64	string	body
group_id If specified, then only actions under the given group will be queried.	bytes	string	body

litrpc.ListActionsResponse

Source: firewall.proto

Field	gRPC Type	REST Type
actions A list of actions performed by the autopilot server.	Action[]	array
last_index_offset The index of the last item in the set of returned actions. This can be used to seek further, pagination style.	uint64	string
total_count The total number of actions that matched the filter in the request. It is only set if count_total was set in the request.	uint64	string

Nested Messages

litrpc.Action

Field	gRPC Type	REST Type
actor_name The name of the actor that initiated the action.	string	string
feature_name The name of the feature that triggered the action.	string	string
trigger A human readable reason that the action was performed.	string	string
intent A human readable string describing the intended outcome successfully performing the action.	string	string
structured_json_data Structured info added by the action performer.	string	string
rpc_method The URI of the method called.	string	string
rpc_params_json The parameters of the method call in compact json form.	string	string
timestamp The unix timestamp in seconds at which the action was attempted.	uint64	string
state The action state. See ActionState for the meaning of each state.	ActionState	string
error_reason If the state is Error, then this string will show the human readable reason for why the action errored out.	string	string
session_id The ID of the session under which the action was performed.	bytes	string

Enums

litrpc.ActionState

Name	Number
STATE_UNKNOWN No state was assigned to the action. This should never be the case.	0
STATE_PENDING Pending means that the request resulting in the action being created came through but that no response came back from the appropriate backend. This means that the Action is either still being processed or that it did not successfully complete.	1
STATE_DONE Done means that the action successfully completed.	2
STATE_ERROR Error means that the Action did not successfully complete.	3