The lc executable provides a command-line interface to interact with a Lumina server and its contents.
NOTE: 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
Options:
Short form
Long form
Description
-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
None
--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 [...])
-t
--time-range RANGE
-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
None
--last-change
Examples:
# Example: List the last 8 changes ("-m 8" specifies the number of changes to show; the default order is reverse-chronological)
alice@alice_PC$ lc hist show -m 8
Change Time Push Func name
------ ------------------- ---- ---------------------------
507 2022-09-15 14:48:18 5 math_things
506 2022-09-15 14:48:17 4 calc_things (*)
505 2022-09-15 14:48:17 4 start
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a
503 2022-09-15 14:48:16 3 display_keygen_window
502 2022-09-15 14:48:15 2 fstat
501 2022-09-15 14:48:15 2 __umoddi3
500 2022-09-15 14:48:15 2 __udivdi3
# Shown 8 results (more are available...)
# Example: List changes from id 9 up to (but excluding) id 14
alice@alice_PC$ lc hist show -r9..14
Change Time Push Func name
------ ------------------- ---- ---------------------
13 2022-09-15 14:48:05 2 AllocateBucketGroup
12 2022-09-15 14:48:05 2 addr_map_find
11 2022-09-15 14:48:05 2 addr_map_insert
10 2022-09-15 14:48:05 2 addr_map_compare_func
9 2022-09-15 14:48:05 2 addr_map_free_func
# Shown 5 results
# Example: List changes using multiple ranges (9..14,505..515; in this case, there were no changes after 507 in the database)
alice@alice_PC$ lc hist show -r9..14,505..515
Change Time Push Func name
------ ------------------- ---- ---------------------
507 2022-09-15 14:48:18 5 math_things
506 2022-09-15 14:48:17 4 calc_things (*)
505 2022-09-15 14:48:17 4 start
13 2022-09-15 14:48:05 2 AllocateBucketGroup
12 2022-09-15 14:48:05 2 addr_map_find
11 2022-09-15 14:48:05 2 addr_map_insert
10 2022-09-15 14:48:05 2 addr_map_compare_func
9 2022-09-15 14:48:05 2 addr_map_free_func
# Shown 8 results
# Example: Find changes from a specific idb file ("-i"), showing the function hash and ea ("-a" adds additional columns to the output)
alice@alice_PC$ lc hist show -i C:\malware\apts\pc_keygenme_3.pe.idb -a calcrel_hash,func_ea
Change Time Push Func name Func EA Func hash
------ ------------------- ---- --------------------------- ------- --------------------------------
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a 4011e2 420A0485EDB7C6774E1822953FB785D4
503 2022-09-15 14:48:16 3 display_keygen_window 401099 ACA673D198FBC0DF24C20A15FF7F25CE
# Shown 2 results
# Example: Show the first 4 changes ("-m4") with their input file(s) (in "--chronological" order; "-a" adds an additional column)
alice@alice_PC$ lc hist show --chronological -m 4 -a input_path
Change Time Push Func name Input path
------ ------------------- ---- --------------------- ------------------------------------
1 2022-09-15 14:47:44 1 .init_proc /home/alice/work/pc_dwarf_arrays.elf
2 2022-09-15 14:47:44 1 _start /home/alice/work/pc_dwarf_arrays.elf
3 2022-09-15 14:47:44 1 __do_global_dtors_aux /home/alice/work/pc_dwarf_arrays.elf
4 2022-09-15 14:47:44 1 frame_dummy /home/alice/work/pc_dwarf_arrays.elf
# Shown 4 results (more are available...)
# Example: Show the last change by a user ("-u" indicates the user, "-m1" means show 1 change only, "-a" adds an additional column)
alice@alice_PC$ lc hist show -ubob -m1 -a username
Change Time Push Func name Username
------ ------------------- ---- --------- --------
502 2022-09-15 14:48:15 2 fstat bob
# Shown 1 results (more are available...)
# Example: Show up to 4 changes ("-m4") between two dates ("-t" indicates a range of "YYYY-MM-DD" dates)
alice@alice_PC$ lc hist show -m4 -t2022-09-02..2022-12-03
Change Time Push Func name
------ ------------------- ---- ---------------------------
507 2022-09-15 14:48:18 5 math_things
506 2022-09-15 14:48:17 4 calc_things (*)
505 2022-09-15 14:48:17 4 start
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a
# Shown 4 results (more are available...)
# Example: 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)
alice@alice_PC$ lc hist show -m4 -t-2w..-5M -a func_id
Change Time Push Func name Func ID
------ ------------------- ---- --------------------------- -------
507 2022-09-15 14:48:18 5 math_things 506
506 2022-09-15 14:48:17 4 calc_things (*) 506
505 2022-09-15 14:48:17 4 start 505
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a 504
# Shown 4 results (more are available...)
# Example: 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
alice@alice_PC$ lc hist show -m4 -t-2w..-5M -a func_id --last-change
Change Time Push Func name Func ID
------ ------------------- ---- --------------------------- -------
507 2022-09-15 14:48:18 5 math_things 506
505 2022-09-15 14:48:17 4 start 505
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a 504
503 2022-09-15 14:48:16 3 display_keygen_window 503
# Shown 4 results (more are available...)
# Example: Show up to 4 changes ("-m4"), occurring after a "now"-relative date ("-t", from 6 hours ago up to now)
alice@alice_PC$ lc hist show -m4 -t-6H
Change Time Push Func name
------ ------------------- ---- ---------------------------
507 2022-09-15 14:48:18 5 math_things
506 2022-09-15 14:48:17 4 calc_things (*)
505 2022-09-15 14:48:17 4 start
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a
# Shown 4 results (more are available...)
# Example: Show changes about a specific function name ("-n")
alice@alice_PC$ lc hist show -n print_relocinfo
Change Time Push Func name
------ ------------------- ---- ---------------
175 2022-09-15 14:48:08 2 print_relocinfo
# Shown 1 results
# Example: Show changes about a function name ("-n") searched by wildcard ("like:...")
alice@alice_PC$ lc hist show -n "like:%reloc%info%"
Change Time Push Func name
------ ------------------- ---- --------------------------
179 2022-09-15 14:48:08 2 print_reloc_information_32
178 2022-09-15 14:48:08 2 print_reloc_information_64
177 2022-09-15 14:48:08 2 print_relocinfo_32
176 2022-09-15 14:48:08 2 print_relocinfo_64
175 2022-09-15 14:48:08 2 print_relocinfo
# Shown 5 results
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)
None
--chronological
Display entries in chronological order (defaults to reverse-chronological).
Examples:
alice@alice_PC$ lc hist pushes
Push ID Time User name IDB path
------- ------------------- --------- ----------------------------------------
5 2022-09-15 14:48:18 alice /home/alice/work/pc_math_b_64.elf.i64
4 2022-09-15 14:48:17 alice /home/alice/work/pc_math_a_64.elf.i64
3 2022-09-15 14:48:16 damian C:\malware\apts\pc_keygenme_3.pe.idb
2 2022-09-15 14:48:05 bob /Users/bob/idbs/pc_dwarfdump.elf.idb
1 2022-09-15 14:47:44 alice /home/alice/work/pc_dwarf_arrays.elf.idb
# Shown 5 results
# Example: List all pushes from a specific license ID
alice@alice_PC$ lc hist pushes -l BB-0B0B-AC8E-01 -a license_email
Push ID Time User name License email IDB path
------- ------------------- --------- ------------- ------------------------------------
2 2022-09-15 14:48:05 bob bob@acme.com /Users/bob/idbs/pc_dwarfdump.elf.idb
# Shown 1 results
# Example: List all pushes from licenses with IDs matching a pattern ("-a" adds an additional column)
alice@alice_PC$ lc hist pushes -l like:AA-% -a license_id
Push ID Time User name License ID IDB path
------- ------------------- --------- --------------- ----------------------------------------
5 2022-09-15 14:48:18 alice AA-A11C-AC8E-01 /home/alice/work/pc_math_b_64.elf.i64
4 2022-09-15 14:48:17 alice AA-A11C-AC8E-01 /home/alice/work/pc_math_a_64.elf.i64
1 2022-09-15 14:47:44 alice AA-A11C-AC8E-01 /home/alice/work/pc_dwarf_arrays.elf.idb
# Shown 3 results
# Example: Show the first push
alice@alice_PC$ lc hist pushes --chronological -m 1
Push ID Time User name IDB path
------- ------------------- --------- ----------------------------------------
1 2022-09-15 14:47:44 alice /home/alice/work/pc_dwarf_arrays.elf.idb
# Shown 1 results (more are available...)
# Example: List all pushes between two timestamps
alice@alice_PC$ lc hist pushes -t"2022-09-07 10:20:00..2022-12-31"
Push ID Time User name IDB path
------- ------------------- --------- ----------------------------------------
5 2022-09-15 14:48:18 alice /home/alice/work/pc_math_b_64.elf.i64
4 2022-09-15 14:48:17 alice /home/alice/work/pc_math_a_64.elf.i64
3 2022-09-15 14:48:16 damian C:\malware\apts\pc_keygenme_3.pe.idb
2 2022-09-15 14:48:05 bob /Users/bob/idbs/pc_dwarfdump.elf.idb
1 2022-09-15 14:47:44 alice /home/alice/work/pc_dwarf_arrays.elf.idb
# Shown 5 results
# Example: List all pushes from two users ("-a" adds an additional column)
alice@alice_PC$ lc hist pushes -u"bob damian" -a"license_name license_id"
Push ID Time User name License name License ID IDB path
------- ------------------- --------- ------------ --------------- ------------------------------------
3 2022-09-15 14:48:16 damian Damian DD-DA81-A000-01 C:\malware\apts\pc_keygenme_3.pe.idb
2 2022-09-15 14:48:05 bob Bob BB-0B0B-AC8E-01 /Users/bob/idbs/pc_dwarfdump.elf.idb
# Shown 2 results
hist del
hist del [OPTION]
Deletes history and metadata for functions.
Options:
Short form
Long form
Description
-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 [...])
-t
--time-range RANGE
-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
None
--last-change
Examples:
# Example: Display the last 10 changes, with their input file(s) and function ID(s)
alice@alice_PC$ show -m10 -a input_path
Change Time Push Func name Func ID Input path
------ ------------------- ---- --------------------------- ------- ---------------------------------
507 2022-09-15 14:48:18 5 math_things 506 /home/alice/work/pc_math_b_64.elf
506 2022-09-15 14:48:17 4 calc_things (*) 506 /home/alice/work/pc_math_a_64.elf
505 2022-09-15 14:48:17 4 start 505 /home/alice/work/pc_math_a_64.elf
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a 504 C:\malware\apts\pc_keygenme_3.pe
503 2022-09-15 14:48:16 3 display_keygen_window 503 C:\malware\apts\pc_keygenme_3.pe
502 2022-09-15 14:48:15 2 fstat 502 /Users/bob/idbs/pc_dwarfdump.elf
501 2022-09-15 14:48:15 2 __umoddi3 501 /Users/bob/idbs/pc_dwarfdump.elf
500 2022-09-15 14:48:15 2 __udivdi3 500 /Users/bob/idbs/pc_dwarfdump.elf
499 2022-09-15 14:48:14 2 dwarf_get_ADDR_name 499 /Users/bob/idbs/pc_dwarfdump.elf
498 2022-09-15 14:48:14 2 dwarf_get_FRAME_name 498 /Users/bob/idbs/pc_dwarfdump.elf
# Shown 10 results (more are available...)
# Example: Delete all changes stemming from a specific file
alice@alice_PC$ lc hist del -s -f/Users/bob/idbs/pc_dwarfdump.elf
228 entries deleted from history
# Example: Delete one single change
alice@alice_PC$ lc hist del -s -r505..506
1 entries deleted from history
# Example: Delete all the changes from push 1
alice@alice_PC$ lc hist del -s -p 1..2
7 entries deleted from history
alice@alice_PC$ hist show -a username
Change Time Push Func name Username
------ ------------------- ---- --------------------------- --------
507 2022-09-15 14:48:18 5 math_things alice
506 2022-09-15 14:48:17 4 calc_things (*) alice
504 2022-09-15 14:48:16 3 keygen_window_dialog_proc_a damian
503 2022-09-15 14:48:16 3 display_keygen_window damian
# Shown 4 results
# Example: Delete all changes by a user
alice@alice_PC$ lc hist del -s -udamian
2 entries deleted from history
alice@alice_PC$ hist show -a func_id
Change Time Push Func name Func ID
------ ------------------- ---- --------------- -------
507 2022-09-15 14:48:18 5 math_things 506
506 2022-09-15 14:48:17 4 calc_things (*) 506
# Shown 2 results
# Example: Delete the last change for a function
alice@alice_PC$ lc hist del -s --func math_things --last-change
1 entries deleted from history
alice@alice_PC$ hist show -a func_id
Change Time Push Func name Func ID
------ ------------------- ---- ----------- -------
506 2022-09-15 14:48:17 4 calc_things 506
# Shown 1 results
# Example: Delete all remaining changes for a function by name
alice@alice_PC$ lc hist del -s --func calc_things
1 entries deleted from history
alice@alice_PC$ hist show
# Shown 0 results
Various information
info
info
Shows lumina connection information.
Example:
alice@alice_PC$ lc info
Hex-Rays Lumina Server v8.0
Lumina time: 2022-08-29 10:13:37, up since 2022-08-21 21:00:05
MAC address: FF:32:67:FF:D3:00
Client name: alice *ADMIN*
Client host: 127.0.0.1
users
users
Shows users.
Example:
alice@alice_PC$ lc users
LastActive Adm Login License User name Email
---------- --- ------ --------------- --------------------------- ------------------
2022-08-29 * bob XX-XXXX-XXXX-XX bob bob@acme.com
2022-08-29 * alice XX-XXXX-XXXX-XX alice alice@acme.com
2022-08-27 damian XX-XXXX-XXXX-XX damian damian@acme.com
stats
stats [OPTION]
Shows the numbers of functions, pushes, history records, IDBs and input files stored in the Lumina server database.
Options:
Short form
Long form
Description
-u
--username USERNAME
username(s) to operate on
Examples:
alice@alice_PC$ lc stats
Consolidated statistics from lumina_server:
Number of functions: 4
Number of pushes: 5
Number of history records: 6
Number of IDBs: 3
Number of input files: 3
---------------------------------------------
# Example: Retrieve the statistics for a list of users
alice@alice_PC$ lc stats -ualice,bob,russ
Statistics for alice:
Number of functions: 2
Number of pushes: 3
Number of history records: 4
Number of IDBs: 1
Number of input files: 1
---------------------------------------------
Statistics for bob:
Number of functions: 1
Number of pushes: 1
Number of history records: 1
Number of IDBs: 1
Number of input files: 1
---------------------------------------------
Administrative commands
These commands require that the user executing them has admin privileges.
Managing users
Locally managing users
The following commands allow the administrator to manipulate users known to the Lumina server (provided
of course the Lumina server doesn't delegate users management to the Teams server)
user add
user add USERNAME EMAIL IS_ADMIN LICENSE_ID
Adds a user.
USERNAME
The username of the user.
EMAIL
The email address of the user.
IS_ADMIN
Should be 1 if the user is admin, otherwise 0.
LICENSE_ID
The license of the user.
Example:
alice@alice_PC$ lc user add damiank damian@acme.com 0 XX-XXXX-XXXX-XX
user edit
user edit USERNAME EMAIL IS_ADMIN LICENSE_ID
Edits a user definition.
USERNAME
The username of the user to modify.
EMAIL
The email address of the user.
IS_ADMIN
Should be 1 if the user is admin, otherwise 0.
LICENSE_ID
The license of the user.
Example:
# Example: For the given username, set the email, admin flag and license ID
alice@alice_PC$ lc user edit damiank damiank@acme.com 0 XX-XXXX-XXXX-XX
user del
user del USERNAME EMAIL LICENSE_ID
Deletes a user.
USERNAME
The name of the user to delete.
EMAIL
The email address of the user.
LICENSE_ID
The license of the user.
Example:
alice@alice_PC$ lc user del damiank damiank@acme.com XX-XXXX-XXXX-XX
passwd
passwd PASS USER
Modifies the password for a user.
PASS
The new password.
USER
The username whose password should be changed Only admins can change other users' passwords.
Example:
alice@alice_PC$ lc passwd secret_password john
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.
For each connection, the currently executed query (if any) is shown.
Example:
alice@alice_PC$ lc session list
id=1642 peer="127.0.0.1", user="...", license="...", e-mail="...", established="2022-08-16 17:13:21"
current_query="INSERT INTO pushes (fk_idb, fk_user) VALUES (?, ?)" (0msec)
session kill
session kill ID
Kills an existing connection to the Lumina server.
ID
The connection to kill, as shown by the <<cmd_session-list>> command
Example:
alice@alice_PC$ lc session list
id=1 peer="127.0.0.1", user="...", license="...", e-mail="...", established="2022-09-20 16:47:07" current_query="" (0msec)
alice@alice_PC$ lc session kill 1
Connection killed
alice@alice_PC$ lc session list
No connections.
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.
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 is the role of the 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.
TIP: Wildcards can be used to facilitate the usage of options that take strings as input.
See the .
time range to operate on (start..end) see the
Select only the last change for a function (which )
time range to operate on (start..end) see the
Select only the last change for a function (which )
User management will depend whether the Lumina server is configured to work
with its own set of users, or .
In the latter case, you should use to administer the Teams server.
The command must be used after creating a user; otherwise the new user will not be able to login to the Lumina server and use it.
