···1+# Changelog
2+3+## [Unreleased] - _TBD_
4+5+## [v0.4.0] - 2024-03-19
6+7+### Added
8+9+- Implemented the function histories command.
10+- Configurable time limits.
11+12+### Fixed
13+14+- RPC HelloResult will now report if deletes are enabled.
15+16+### Changes
17+18+- Applied code formatting using `cargo fmt`
19+20+## [v0.3.0] - 2023-08-22
21+22+### Added
23+24+- This changelog.
25+- Support for IDA 8.1+ delete command.
26+- Pooling for connections to database.
27+- Attempt to cancel immutable database queries if client leaves.
28+- Database migrations via Diesel ORM.
29+- Support for IDA 8.3+ hello response.
30+- Add Metrics for prometheus.
31+32+### Fixed
33+34+- 8K stack size is too small for debug builds.
35+36+## [v0.2.0] - 2022-10-12
37+38+### Added
39+40+- Protocol: support for IDA 8.1+ user authentication.
41+- Client connection duration limitations.
42+43+### Changed
44+45+- Tokio's thread size is reduced from 4M to 8K.
46+47+## [v0.1.0] - 2021-01-21
48+49+This is Lumen's first tagged release. It contains a few fixes and dependency updates since the initial commit (2020-12-17).
50+51+[Unreleased]: https://github.com/naim94a/lumen/compare/v0.4.0...HEAD
52+[v0.4.0]: https://github.com/naim94a/lumen/compare/v0.3.0...v0.4.0
53+[v0.3.0]: https://github.com/naim94a/lumen/compare/v0.2.0...v0.3.0
54+[v0.2.0]: https://github.com/naim94a/lumen/compare/v0.1.0...v0.2.0
55+[v0.1.0]: https://github.com/naim94a/lumen/releases/tag/v0.1.0
···1-# Lumen
2-A private Lumina server that can be used with IDA Pro 7.2+.
3-4-[lumen.abda.nl](https://lumen.abda.nl/) runs this server.
5-6-You can read about the protocol research [here](https://abda.nl/posts/introducing-lumen/).
7-8-## Features
9-- Stores function signatures so you (and your team) can quickly identify functions that you found in the past using IDA's built-in Lumina features.
10-- Backed by PostgreSQL
11-- Experimental HTTP API that allows querying the database for comments by file or function hash.
12-13-## Getting Started
14-### Binary releases
15-Release binaries are available at https://github.com/naim94a/lumen/releases/latest.
16-17-### Building from source with Rust
18-1. `git clone https://github.com/naim94a/lumen.git`
19-2. Get a rust toolchain: https://rustup.rs/
20-3. `cd lumen`
21-4. Setup a Postgres database and execute src/schema.sql on it
22-5. `cargo build --release`
23-24-### Docker Method
25-1. Install `docker-engine` and `docker-compose`.
26-2. If using a custom TLS certificate, copy the private key (`.p12`/`.pfx` extension) to `./dockershare` and set the key password in `.env` as `PKCSPASSWD`.
27-3. If using a custom Lumen config, copy it to `./dockershare/config.toml`.
28-4. Otherwise, or if you have finished these steps, just run `docker-compose up`.
29-5. Regardless, if TLS is enabled in the `config.toml`, a `hexrays.crt` will be generated in `./dockershare` to be copied to the IDA install directory.
30-31-### Usage
32-```
33-./lumen -c config.toml
34-```
35-36-### Configuring IDA
37-You will need IDA Pro 7.2 or above in order to use _lumen_.
38-39-> The following information may get sent to _lumen_ server: IDA key, Hostname, IDB path, original file path, file MD5, function signature, stack frames & comments.
40-41-- In your IDA's installation directory open "cfg\ida.cfg" with your favorite text editor _(Example: C:\Program Files\IDA Pro 7.5\cfg\ida.cfg)_
42-- Locate the commented out `LUMINA_HOST`, `LUMINA_PORT`, and change their values to the address of your _lumen_ server.
43-- If you didn't configure TLS, Add "LUMINA_TLS = NO" after the line with `LUMINA_PORT`.
44-45-Example:
46-```C
47-LUMINA_HOST = "192.168.1.1";
48-LUMINA_PORT = 1234
49-50-// Only if TLS isn't used:
51-LUMINA_TLS = NO
52-```
53-54-### Configuring TLS
55-IDA Pro uses a pinned certificate for Lumina's communcation, so adding a self-signed certificate to your root certificates won't work.
56-Luckily, we can override the hard-coded public key by writing a DER-base64 encoded certificate to "hexrays.crt" in IDA's install directory.
57-58-You may find the following commands useful:
59-```bash
60-# create a certificate
61-openssl req -x509 -newkey rsa:4096 -keyout lumen_key.pem -out lumen_crt.pem -days 365 -nodes
62-63-# convert to pkcs12 for lumen; used for `lumen.tls` in config
64-openssl pkcs12 -export -out lumen.p12 -inkey lumen_key.pem -in lumen_crt.pem
65-66-# export public-key for IDA; Copy hexrays.crt to IDA installation folder
67-openssl x509 -in lumen_crt.pem -out hexrays.crt
68-```
69-70-No attempt is made to merge function data - this may casuse a situation where metadata is inconsistent.
71-Instead, the metadata with the highest calculated score is returned to the user.
72-73-74----
75-76-Developed by [Naim A.](https://github.com/naim94a); License: MIT.
0000000000000000000000000000000000000000000000000
···1+# Lumen
2+3+A private Lumina server that can be used with IDA Pro 7.2+.
4+5+[lumen.abda.nl](https://lumen.abda.nl/) runs this server.
6+7+You can read about the protocol research [here](https://abda.nl/posts/introducing-lumen/).
8+9+## Features
10+11+- Stores function signatures so you (and your team) can quickly identify functions that you found in the past using IDA's built-in Lumina features.
12+- Backed by PostgreSQL
13+- Experimental HTTP API that allows querying the database for comments by file or function hash.
14+15+## Getting Started
16+17+### Docker Method (Recommended)
18+19+In this method precompiled docker images will be downloaded, All you need is [docker-compose.yml](./docker-compose.yml).
20+21+1. Install `docker-engine` and `docker-compose`.
22+2. If using a custom TLS certificate, copy the private key (`.p12`/`.pfx` extension) to `./dockershare` and set the key password in `.env` as `PKCSPASSWD`.
23+3. If using a custom Lumen config, copy it to `./dockershare/config.toml`.
24+4. Otherwise, or if you have finished these steps, just run `docker-compose up`.
25+5. Regardless, if TLS is enabled in the `config.toml`, a `hexrays.crt` will be generated in `./dockershare` to be copied to the IDA install directory.
26+27+### Building from source with Rust
28+29+1. `git clone https://github.com/naim94a/lumen.git`
30+2. Get a rust toolchain: https://rustup.rs/
31+3. `cd lumen`
32+4. Setup a the database
33+34+ - install postgres
35+ - install diesel-cli and run migrations:
36+37+ ```bash
38+ cargo install diesel_cli --no-default-features -Fpostgres
39+ diesel --config-file common/diesel.toml \
40+ --database-url postgres://postgres:password@localhost/lumen \
41+ migration run
42+ ```
43+44+5. `cargo build --release`
45+46+### Usage
47+48+```bash
49+./lumen -c config.toml
50+```
51+52+### Configuring IDA
53+54+#### IDA Pro >= 8.1
55+56+If you used LUMEN in the past, remove the LUMINA settings in the ida.cfg or idauser.cfg files, otherwise you will get a warning about
57+bad config parameters.
58+59+##### Setup under Linux :
60+61+```bash
62+#!/bin/sh
63+export LUMINA_TLS=false
64+$1
65+```
66+67+- save as ida_lumen.sh, "chmod +x ida_lumen.sh", now you can run IDA using "./ida_lumen.sh ./ida" or "./ida_lumen ./ida64"
68+69+##### Setup under Windows :
70+71+```batch
72+set LUMINA_TLS=false
73+%1
74+```
75+76+- save as ida_lumen.bat, now you can run IDA using "./ida_lumen.bat ida.exe" or "./ida_lumen.bat ida64.exe"
77+78+##### Setup IDA
79+80+- Go to Options, General, Lumina. Select "Use a private server", then set your host and port and "guest" as username and password. Click on ok.
81+82+#### IDA Pro < 8.1
83+84+You will need IDA Pro 7.2 or above in order to use _lumen_.
85+86+> The following information may get sent to _lumen_ server: IDA key, Hostname, IDB path, original file path, file MD5, function signature, stack frames & comments.
87+88+- In your IDA's installation directory open "cfg\ida.cfg" with your favorite text editor _(Example: C:\Program Files\IDA Pro 7.5\cfg\ida.cfg)_
89+- Locate the commented out `LUMINA_HOST`, `LUMINA_PORT`, and change their values to the address of your _lumen_ server.
90+- If you didn't configure TLS, Add "LUMINA_TLS = NO" after the line with `LUMINA_PORT`.
91+92+Example:
93+94+```C
95+LUMINA_HOST = "192.168.1.1";
96+LUMINA_PORT = 1234
97+98+// Only if TLS isn't used:
99+LUMINA_TLS = NO
100+```
101+102+### Configuring TLS
103+104+IDA Pro uses a pinned certificate for Lumina's communcation, so adding a self-signed certificate to your root certificates won't work.
105+Luckily, we can override the hard-coded public key by writing a DER-base64 encoded certificate to "hexrays.crt" in IDA's install directory.
106+107+You may find the following commands useful:
108+109+```bash
110+# create a certificate
111+openssl req -x509 -newkey rsa:4096 -keyout lumen_key.pem -out lumen_crt.pem -days 365 -nodes
112+113+# convert to pkcs12 for lumen; used for `lumen.tls` in config
114+openssl pkcs12 -export -out lumen.p12 -inkey lumen_key.pem -in lumen_crt.pem
115+116+# export public-key for IDA; Copy hexrays.crt to IDA installation folder
117+openssl x509 -in lumen_crt.pem -out hexrays.crt
118+```
119+120+No attempt is made to merge function data - this may cause a situation where metadata is inconsistent.
121+Instead, the metadata with the highest calculated score is returned to the user.
122+123+---
124+125+Developed by [Naim A.](https://github.com/naim94a); License: MIT.
···1+# For documentation on how to configure this file,
2+# see https://diesel.rs/guides/configuring-diesel-cli
3+4+[print_schema]
5+file = "src/db/schema_auto.rs"
6+7+[migrations_directory]
8+dir = "migrations"
···1+-- This file was automatically created by Diesel to setup helper functions
2+-- and other internal bookkeeping. This file is safe to edit, any future
3+-- changes will be added to existing projects as new migrations.
4+5+DROP FUNCTION IF EXISTS diesel_manage_updated_at(_tbl regclass);
6+DROP FUNCTION IF EXISTS diesel_set_updated_at();
···1+-- This file was automatically created by Diesel to setup helper functions
2+-- and other internal bookkeeping. This file is safe to edit, any future
3+-- changes will be added to existing projects as new migrations.
4+5+6+7+8+-- Sets up a trigger for the given table to automatically set a column called
9+-- `updated_at` whenever the row is modified (unless `updated_at` was included
10+-- in the modified columns)
11+--
12+-- # Example
13+--
14+-- ```sql
15+-- CREATE TABLE users (id SERIAL PRIMARY KEY, updated_at TIMESTAMP NOT NULL DEFAULT NOW());
16+--
17+-- SELECT diesel_manage_updated_at('users');
18+-- ```
19+CREATE OR REPLACE FUNCTION diesel_manage_updated_at(_tbl regclass) RETURNS VOID AS $$
20+BEGIN
21+ EXECUTE format('CREATE TRIGGER set_updated_at BEFORE UPDATE ON %s
22+ FOR EACH ROW EXECUTE PROCEDURE diesel_set_updated_at()', _tbl);
23+END;
24+$$ LANGUAGE plpgsql;
25+26+CREATE OR REPLACE FUNCTION diesel_set_updated_at() RETURNS trigger AS $$
27+BEGIN
28+ IF (
29+ NEW IS DISTINCT FROM OLD AND
30+ NEW.updated_at IS NOT DISTINCT FROM OLD.updated_at
31+ ) THEN
32+ NEW.updated_at := current_timestamp;
33+ END IF;
34+ RETURN NEW;
35+END;
36+$$ LANGUAGE plpgsql;
+39
common/migrations/2023-02-01-210714_init/up.sql
···000000000000000000000000000000000000000
···1+CREATE TABLE IF NOT EXISTS users (
2+ id SERIAL PRIMARY KEY,
3+ lic_id bytea,
4+ lic_data bytea,
5+ hostname VARCHAR(260),
6+ first_seen TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
7+);
8+CREATE UNIQUE INDEX IF NOT EXISTS user_rec ON users(lic_id,lic_data,hostname);
9+CREATE UNIQUE INDEX IF NOT EXISTS user_hn_null ON users (lic_id,lic_data, (hostname IS NULL)) WHERE hostname is NULL;
10+11+CREATE TABLE IF NOT EXISTS files (
12+ id SERIAL PRIMARY KEY,
13+ chksum bytea UNIQUE /* file chksum */
14+);
15+16+CREATE TABLE IF NOT EXISTS dbs (
17+ id SERIAL PRIMARY KEY,
18+ file_path VARCHAR(260),
19+ idb_path VARCHAR(260),
20+ file_id INTEGER REFERENCES files(id),
21+ user_id INTEGER REFERENCES users(id)
22+);
23+CREATE UNIQUE INDEX IF NOT EXISTS db_paths ON dbs(file_id, user_id, idb_path);
24+25+CREATE TABLE IF NOT EXISTS funcs (
26+ id SERIAL PRIMARY KEY,
27+ name TEXT NOT NULL,
28+ len INTEGER NOT NULL,
29+ db_id INTEGER REFERENCES dbs(id) NOT NULL,
30+ chksum bytea, /* function chksum */
31+ metadata bytea,
32+ rank INTEGER,
33+34+ push_dt TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
35+ update_dt TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
36+);
37+CREATE UNIQUE INDEX IF NOT EXISTS funcs_db ON funcs(chksum, db_id);
38+CREATE INDEX IF NOT EXISTS funcs_ranking ON funcs(chksum,rank);
39+CREATE INDEX IF NOT EXISTS func_chksum ON funcs(chksum);
···6# server display name; appears in IDA output window
7server_name = "lumen"
8000009# only required when `use_tls` is set to true.
10[lumina.tls]
11# Specify the server's certificate.
···1516[database]
17# Specifies a postgresql connection string. All variables can be found here: https://docs.rs/tokio-postgres/0.6.0/tokio_postgres/config/struct.Config.html
18-connection_info = "host=127.0.0.1 port=49153 user=postgres password=1"
19# Sets if the database connection should be made using TLS.
20use_tls = false
21# If the database requires a secure connection, paths to server-ca and client-id certificates can be set here:
···6# server display name; appears in IDA output window
7server_name = "lumen"
89+# Allow clients to delete metadata from the database?
10+allow_deletes = false
11+# How many function histories should we return? 0=Disabled.
12+get_history_limit = 50
13+14# only required when `use_tls` is set to true.
15[lumina.tls]
16# Specify the server's certificate.
···2021[database]
22# Specifies a postgresql connection string. All variables can be found here: https://docs.rs/tokio-postgres/0.6.0/tokio_postgres/config/struct.Config.html
23+connection_info = "postgres://postgres:1@127.0.0.1/postgres"
24# Sets if the database connection should be made using TLS.
25use_tls = false
26# If the database requires a secure connection, paths to server-ca and client-id certificates can be set here: