Teams lc command reference manual

Last updated 5 months ago

Was this helpful?

Introduction

The lc executable provides a command-line interface to interact with a Lumina server and its contents.

virtually all the commands described in this document, require administrator rights; "regular" users will typically not have the necessary privileges.

Command-line options

-h, --host HOSTNAME[:PORT] Lumina host name and port (if port is omitted, it defaults to 443)

-u USERNAME specify username

-p PASSWORD specify password

-v, --verbose verbose output

In order to connect to a Lumina server, lc must at least be provided with a hostname and a valid user-password pair.

In order to keep the various commands' syntax as clear as possible, we will omit the login options from commands for the rest of this manual.

Other options exists, specific to each lc command (see ).

Commands

The following commands are accepted by lc:

Operating with metadata

Commands in this section let users view metadata stored in the Lumina server and their history.

`hist show`

hist show [OPTION]

Queries history of changes for function(s).

The following informations will be displayed for each change:

The ID of the change
The timestamp of the change
The ID of the push that contains the change
The name of the function at that change (+ (*) if it has been modified past this change)
optional: The username of the user that pushed this change
optional: The name of the license associated with the push for this change
optional: The email of the license associated with the push for this change
optional: The ID of the license associated with the push for this change
optional: The ID of the function
optional: The effective address (EA) of the function in the input file for the change
optional: The hash of the function
optional: The path of the idb file where the change came from
optional: The hash of the file where the change came from
optional: The path of the file where the change came from

-a, --additional-fields LIST Comma-delimited list of additional info to display (username, license_name, license_email, license_id, func_id, func_ea, calcrel_hash, idb_path, input_hash, input_path, all)

-d, --details Show details (diff-like) for each change

--chronological Display entries in chronological order (defaults to reverse-chronological).

-m, --max-entries NUMBER maximum number of entries to fetch (defaults to 100)

-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on

-r, --history-id-range RANGE history ID range(s) to operate on (start0..end0 […])

-i, --idb IDB IDB name(s) to operate on

-f, --input FILE input file(s) to operate on

-u, --username USERNAME username(s) to operate on

-n, --func NAME function name(s) to operate on

-h, --input-hash HASH input file hash(es) to operate on

-p, --pushes-id-range RANGE Pushes ID range(s) to operate on (start0..end0 […])

-c, --calcrel-hash HASH function hash(es) to operate on

Examples:

List the last 8 changes ("-m 8" specifies the number of changes to show; the default order is reverse-chronological)

List changes from id 9 up to (but excluding) id 14

List changes using multiple ranges (9..14,505..515; in this case, there were no changes after 507 in the database)

Find changes from a specific idb file ("-i"), showing the function hash and ea ("-a" adds additional columns to the output)

Show the first 4 changes ("-m4") with their input file(s) (in "--chronological" order; "-a" adds an additional column)

Show the last change by a user ("-u" indicates the user, "-m1" means show 1 change only, "-a" adds an additional column)

Show up to 4 changes ("-m4") between two dates ("-t" indicates a range of "YYYY-MM-DD" dates)

Show up to 4 changes ("-m4") between two "now"-relative dates ("-t", from 2 weeks ago to 5 minutes ago) ("-a" adds an additional column)

Show up to 4 changes ("-m4") between two "now"-relative dates ("-t", from 2 weeks ago to 5 minutes ago) ("-a" adds an additional column), only select the last change for each function

Show up to 4 changes ("-m4"), occurring after a "now"-relative date ("-t", from 6 hours ago up to now)

Show changes about a specific function name ("-n")

Show changes about a function name ("-n") searched by wildcard ("like:…")

Show metadata details ("--details") in changes for a function ("-n"); this particular change added a new function

`hist pushes`

hist pushes [OPTION]

Shows pushes to the Lumina server.

-a, --additional-fields LIST Comma-delimited list of additional info to display (license_name, license_email, license_id, all)

-t, --time-range TIMESTAMP timestamp

-u, --username USERNAME username(s) to operate on

-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on

-m, --max-entries NUMBER maximum number of entries to operate on (defaults to 100)

--chronological Display entries in chronological order (defaults to reverse-chronological).

Examples:

List all pushes from a specific license ID

List all pushes from licenses with IDs matching a pattern ("-a" adds an additional column)

Show the first push

List all pushes between two timestamps

List all pushes from two users ("-a" adds an additional column)

`hist del`

hist del [OPTION]

Deletes history and metadata for functions.

-s, --silent Do not ask for confirmation before deleting history

-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on

-r, --history-id-range RANGE history ID range(s) to operate on (start0..end0 […])

-i, --idb IDB IDB name(s) to operate on

-f, --input FILE input file(s) to operate on

-u, --username USERNAME username(s) to operate on

-n, --func NAME function name(s) to operate on

-h, --input-hash HASH input file hash(es) to operate on

-p, --pushes-id-range RANGE Pushes ID range(s) to operate on (start0..end0 […])

-c, --calcrel-hash HASH function hash(es) to operate on

Examples:

Display the last 10 changes, with their input file(s) and function ID(s)

Delete all changes for functions matching a pattern

Delete all changes stemming from a specific file

List the changes from pushes 1 to 5 (not included), showing their input file(s)

Delete one single change

Delete all the changes from push 1

Delete all changes by a user

Delete the last change for a function

Delete all remaining changes for a function by name

Various information

`info`

info

Shows lumina connection information.

Example:

`users`

users

Shows users.

Example:

`stats`

stats [OPTION]

Shows the numbers of functions, pushes, history records, IDBs and input files stored in the Lumina server database.

-u, --username USERNAME username(s) to operate on

Examples:

Retrieve the statistics for a list of users

Administrative commands

These commands require that the user executing them has admin privileges.

Managing users

Users management is delegated to the Hex-Rays Vault server; the administrator will be in charge of performing the adding/editing/deleting of users on the Hex-Rays Vault server itself.

Whenever a user connects to the Lumina server, it will turn to the Hex-Rays Vault server to ask it to perform authentication.

A "shadow" of the user data is nonetheless kept in the Lumina server’s database, in order to be able to attribute contributions.

The host name (and port) of the Hex-Rays Vault server need to be present in the lumina.conf file.

Managing sessions

session list

session list

Lists the current connections to the Lumina server. For each connection, the currently executed query (if any) is shown.

Example:

session kill

session kill ID

Kills an existing connection to the Lumina server.

Parameters

Example:

Concepts

What is the Lumina server

The Lumina server is a "functions metadata" repository.

It is a place where IDA users can push, and pull such metadata, to ease their reverse-engineering work: metadata can be extracted from existing projects, and re-applied effortlessly to new projects, thereby reducing (sometimes dramatically) the amount of time needed to analyze binaries.

Lumina server vs Hex-Rays Vault server: what is the difference?

While the workflow with the Hex-Rays Vault server and associated tools (hv, hvui and IDA’s diff/merge modes) are extremely powerful for working on multiple revisions of the same binaries, the Lumina server in turn eases the replication of past efforts to new projects.

In effect, the Lumina server offers another "dimension" to collaborative reverse-engineering efforts.

Functions metadata

The Lumina server associates "function metadata" to functions, by means of a (md5) hash of those functions: whenever it wants to push information to, or pull information from the server, IDA will first have to compute hashes of the functions it wants to retrieve metadata for, and send those hashes to the Lumina server.

Similarly, when IDA pushes information to the Lumina server, it will first compute hashes for the corresponding functions, extract the metadata corresponding to those from the .idb file, and send those hash+metadata pairs to the server.

Metadata contents

Metadata about functions can include:

function name
function address
function size
function prototype
function [repeatable] comments
instruction-specific [repeatable] comments
anterior/posterior (i.e., "extra") comments
user-defined "stack points" in the function’s frame
the function frame description and stack variables
instructions operands representations

Pushing & overriding metadata

When a user pushes metadata about a function whose md5 hash isn’t present in the database, the Lumina server will simply create a new record for it.

However, when a user pushes metadata about a function whose md5 hash (and associated metadata) is already present in the database, the Lumina server will attempt to "score" the quality of the old metadata and the quality of the new metadata. If the score of the new metadata is higher, the new function metadata will override the previous one.

When a user asks IDA to push all functions to the Lumina server, IDA will automatically skip some functions: those that still have a "dummy" name (e.g., sub_XXXX), or that are below a certain size threshold (i.e., 32 bytes) will be ignored.

Metadata history

The Lumina server retains a history of the metadata associated to functions. Using the lc utility, it is possible to dig into that history, and view changes (detailed diffs, too.)

File contents

It’s worth pointing out that when pushing metadata to the Lumina server, IDA will not push the binary file itself. Only the following metadata about the file itself will be sent:

the name of the input file
the name of the IDB file
a md5 hash of the input file

The Lumina server cannot therefore be used as a backup/repository for binary files & IDBs (that would be the role of the Hex-Rays Vault server)

Commands

String patterns

Options that take strings as inputs can be enhanced through wildcards. The following wildcards are available:

% represents zero, one or multiple characters.

_ represents one character.

To use wildcards in a string, it must be prefixed with like: e.g. -n like:%main%.

Timerange formats

For timeranges, the following syntaxes are supported:

<ts>..<ts> (from timestamp to (but not including) timestamp)
<ts> (only one timestamp)

Where <ts> can be of the form:

yyyy-mm-dd HH:MM:SS: e.g., 2022-09-12 11:38:22
yyyy-mm-dd: e.g., 2020-03-12
+|-<count><unit>: this is a "now-relative" timestamp, where <unit> must be one of w, d, H, M, S for weeks, days, hours, minutes or seconds respectively. E.g., -4d, +5w, -8H, +1H, …

when using the <ts> syntax (i.e., only 1 timestamp is provided, not an actual range), the final range will be either "from now to <ts>", or "from <ts> to now", depending on whether <ts> is before, or after, the present time.

Speed of retrieving changes

Although it may seem like a simple operation, lc hist show is actually a very demanding one: by default it will have to fetch bits of information from multiple tables (e.g., in order to provide information about which change was superseded by a later one.)

This can be significantly sped up through the use of --last-change: this option lets the server issue a much simpler query, resulting in significantly reduced processing time.

Last updated 5 months ago

Was this helpful?