14 releases (breaking)
0.13.0 | Oct 16, 2024 |
---|---|
0.9.0 | Aug 5, 2024 |
0.8.0 | Jul 28, 2024 |
0.1.2 | Oct 29, 2023 |
#1086 in Web programming
22 downloads per month
2MB
5.5K
SLoC
DRACOON Commander RS
What is this?
This is a port of DRACOON Commander - initially a Python3 project to use DRACOON via CLI.
The project serves as a demo client implementation using dco3
- an API wrapper in Rust for DRACOON.
Built with
This project makes use of several awesome crates and uses async Rust throughout the project.
Crates used:
Full dependency list: Cargo.toml
For all DRACOON operations dco3
is used.
Installation
Regular installation
You can download precompiled binaries on the Github releases page: Releases
Rust toolchain
If you have the Rust toolchain installed, you can install this using cargo like so:
cargo install dccmd-rs
If you like it even rougher or would like to contribute, feel free to compile from source:
Clone the repository and either use cargo run
or build your own executable with cargo build
:
git clone https://github.com/unbekanntes-pferd/dccmd-rs.git
cd dccmd-rs
cargo build
What works?
Currently, the following commands are working:
config
- config management of DRACOON Commander (see subcommands below)download
- downloads a file or folder / room from DRACOON to a desired location on disk (encrypted, unencrypted)upload
- uploads a file or folder to a parent in DRACOON (encrypted, unencrypted)ls
- lists all nodes for a given path in DRACOONmkdir
- creates a folder in given path in DRACOONmkroom
- creates a room (inherits permissions) in given path in DRACOONrm
- removes a node by given path in DRACOONcp
- copies node(s) by given path (or search) in DRACOONusers
- user management in DRACOON (see subcommands below)groups
- group management in DRACOON (see subcommands below)reports
- DRACOON Server specific reports
Example usage
For the sake of clarity, the usage of the binary is called dccmd-rs
, regardless of the use via cargo
or a compiled executable.
Downloads
To download a file, use the download command:
dccmd-rs download your.dracoon.domain/some/room/some-file.pdf ./your/path/your-name.pdf
To download a container (room or folder), use the download command with recursive flag:
dccmd-rs download -r your.dracoon.domain/some/room ./your/path
Note: This will create a directory with same name as your container. Sub rooms are not included.
To download a list search result, use the download command with a search string:
dccmd-rs download your.dracoon.domain/some/*.pdf ./your/path
To download a file with no authorization to a public download share (share):
dccmd-rs download your.dracoon.domain/public/download-shares/someLongAccessKey /your/path
Note: This essentially means you need to copy the created share link
Uploads
To upload a file, use the upload command:
dccmd-rs upload ./your/path/your-name.pdf your.dracoon.domain/some/room
Note: Currently, providing a custom name is not implemented.
You can share the file directly and create a share link (default settings) by passing the --share
flag:
dccmd-rs upload ./your/path/your-name.pdf your.dracoon.domain/some/room --share
To upload a folder, use the --recursive
flag:
dccmd-rs upload /your/path your.dracoon.domain/some/room
Note: Currently only absolute paths are supported for recursive uploads.
To upload a file with no authorization to a public upload share (file request):
dccmd-rs upload /your/path your.dracoon.domain/public/upload-shares/someLongAccessKey
Note: This essentially means you need to copy the created share link
Upload options
When uploading, the default resolution strategy is autorename - this means that if a file foo.pdf
uploaded and already present, it is automatically renamed by DRACOON (e.g. to foo (1).pdf
).
In order to change this behavior, you can the pass the following flags / options:
- --overwrite - a file with the same name will be overwritten (essentially creating versions of the same file)
- --keep-share-links - if --overwrite is used, you can additionally keep existing (download) share links for file(s)
Transfers
To transfer a file from DRACOON instance another instance, use the transfer command:
dccmd-rs transfer instance1.domain.com/some/file.pdf instance2.domain.com/some/target/path
Transfer options
These options are analogue to the upload options (see above).
When uploading, the default resolution strategy is autorename - this means that if a file foo.pdf
uploaded and already present, it is automatically renamed by DRACOON (e.g. to foo (1).pdf
).
In order to change this behavior, you can the pass the following flags / options:
- --overwrite - a file with the same name will be overwritten (essentially creating versions of the same file)
- --keep-share-links - if --overwrite is used, you can additionally keep existing (download) share links for file(s)
Listing nodes
To list nodes, use the ls
command:
dccmd-rs ls your.dracoon.domain/some/path
// for root node use a trailing slash
dccmd-rs ls your.dracoon.domain/
// for searches within the room
dccmd-rs ls your.dracoon.domain/*.pdf
// only files
dccmd-rs ls your.dracoon.domain/some/room --filter type:eq:file
Options:
-l
,--long
- prints all details (size, updated by, node id...)-r
,--human-readable
- prints size in human readable format--managed
- shows room as room admin / room manager (rooms w/o permissions)--all
- fetches all items (default: first 500 items)--filter
- filter for specific values (see API docs for filter info)
Deleting nodes
To delete nodes, use the rm
command:
dccmd-rs rm your.dracoon.domain/some/path/some_file.pdf
dccmd-rs rm -r your.dracoon.domain/some/path/some/room
dccmd-rs rm -r your.dracoon.domain/*test
Note: If you intend to delete a container (room or folder), use the recursive flag.
Note: Room deletion always requires additional confirmation.
Note: You can delete the content in a room by using search strings (*
deletes all). This does not include rooms.
Creating folders
To create folders, use the mkdir
command:
dccmd-rs mkdir your.dracoon.domain/some/path/newfolder
To create rooms, use the mkroom
command:
dccmd-rs mkroom your.dracoon.domain/some/path/newroom
# pass optional usernames for admins (example adds admins with usernames foo1, foo2 and foo3)
dccmd-rs mkroom your.dracoon.domain/some/path/newroom -a foo1 -a foo2 -a foo3
# you can additionally inherit permissions using the --inherit-permissions flag
dccmd-rs mkroom your.dracoon.domain/some/path/newroom -a foo1 --inherit-permissions
# you can also set the default classification (example sets to confidential)
dccmd-rs mkroom your.dracoon.domain/some/path/newroom --classification 3
Copying nodes
To copy nodes, use the cp
command:
dccmd-rs cp your.dracoon.domain/some/path /other/path/new/target
# you can pass a search to copy e.g. only csv files
dccmd-rs cp "your.dracoon.domain/some/path/*.csv" /other/path/new/target
# note: if you need to copy to another instance, use *transfer* instead of *cp*
# in that case, the full path is required
Managing users
To import users, you can use the users import some.dracoon.domain.com
command:
# csv header must be 'first_name,last_name,email,login,oidc_id,mfa_enforced'
# the order of these fields does not matter
# login, oidc_id and mfa_enforced are optional but must be present as field
dccmd-rs users import your.dracoon.domain/ /path/to/users.csv
dccmd-rs users import your.dracoon.domain/ /path/to/users.csv --oidc-id 2 # import as OIDC users
To list users, you can use the users ls some.dracoon.domain.com
command:
# optional flags: --all (lists all users, default: 500, paging) --csv (csv format)
# optional flags: --filter (see API docs for filter info)
dccmd-rs users ls your.dracoon.domain/
dccmd-rs users ls your.dracoon.domain/ --csv --all > userlist.csv
dccmd-rs users ls your.dracoon.domain/ --filter userName:cn:foo
To create users, you can use the users create some.dracoon.domain.com
command:
# params: --first-name, --last-name, --email, --login, --oidc-id
dccmd-rs users create your.dracoon.domain/ -f foo -l bar -e foo@bar.com # local user
dccmd-rs users create your.dracoon.domain/ -f foo -l bar -e foo@bar.com --oidc-id 2 # OIDC user
To delete users, you can use the users some.dracoon.domain.com rm
command:
# supported: user id, user login / username
dccmd-rs users rm your.dracoon.domain/ --user-id 2
dccmd-rs users rm your.dracoon.domain/ --user-name foo # short: -u
To fetch specific user info, you can use the users info some.dracoon.domain.com
command:
# supported: user id, user login / username
dccmd-rs users info your.dracoon.domain/ --user-id 2
dccmd-rs users info your.dracoon.domain/ --user-name foo # short: -u
Switch auth methods
You can switch the auth method for a specific subset (or all users) belonging to a current auth method. In order to use it, you need to pass the following parameters:
- current-method - current auth method in DRACOON - valid options: basic (or local), openid (or oidc), active-directory (or ad)
- new-method - new auth method in DRACOON - valid options see above
- current-oidc-id - optional current OIDC config id - must be provided if current method is openid
- new-oidc-id - optional new OIDC config id - must be provided if new method is openid
- current-ad-id - optional current AD config id - must be provided if current method is active-directory
- new-ad-id - optional new AD config id - must be provided if new method is active-directory
- filter - optional user filter - see API docs for details (e.g. email🇨🇳somedomain.com)
- login - optional login transformation (e.g. email, username, firstname.lastname) default: email
# in order to identify AD or openid ids, use the config system-info command (see below)
# switch from basic auth (local) to openid if local user email contains somedomain.com
dccmd-rs users switch-auth --current-method basic --new-method openid --new-oidc-id 99 --filter email:cn:somedomain.com your.dracoon.domain/
# switch from openid with id 88 to openid with id 99 while setting the login as firstname.lastname (replaced by user values)
dccmd-rs users switch-auth --current-method openid --new-method openid --current-oidc-id 88 --new-oidc-id 99 --filter email:cn:somedomain.com your.dracoon.domain/ --login "firstname.lastname"
Enforce MFA (multi-factor authentication)
In order to enforce MFA for a subset of users, you can (e.g. periodically) run the following commands:
# enforce only for local users
dccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local
# enforce only for local users with specific filter (for filter details see API docs)
dccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local --filter email:cn:somedomain.com
# enforce only for a given filter
dccmd-rs users enforce-mfa your.dracoon.domain/ --filter userName:cn:testuser
# enforce for a specific group id (list groups via groups ls command for id)
dccmd-rs users enforce-mfa your.dracoon.domain/ --group-id 99
# combine all: all local users in group 99 with somedomain.com in email
dccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local --group-id 99 --filter email:cn:somedomain.com
Managing groups
To list groups, you can use the groups ls some.dracoon.domain.com
command:
# optional flags: --all (lists all groups, default: 500, paging) --csv (csv format)
# optional flags: --filter (see API docs for filter info)
dccmd-rs groups ls your.dracoon.domain/
dccmd-rs groups ls your.dracoon.domain/ --csv --all > grouplist.csv
dccmd-rs groups ls your.dracoon.domain/ --filter name:eq:foo
To create groups, you can use the groups create some.dracoon.domain.com
command:
# params: --name
dccmd-rs groups create your.dracoon.domain/ --name foo
To delete groups, you can use the groups some.dracoon.domain.com rm
command:
# supported: group id, group name
dccmd-rs groups rm your.dracoon.domain/ --group-id 2
dccmd-rs groups rm your.dracoon.domain/ --group-name foo
Group users
To list group users, you can use the groups users ls some.dracoon.domain.com
command:
# get all group users for every group
dccmd-rs groups users ls your.dracoon.domain/
# list group users in csv format
dccmd-rs groups users ls your.dracoon.domain/ --csv
dccmd-rs groups users ls your.dracoon.domain/ --csv --all > groupusers.csv
# get specific group users (for a group)
dccmd-rs groups users ls your.dracoon.domain/YourGroupName --csv --all
Reports
To fetch reports (either table live view or CSV) of events or permissions, use the respective reports
command:
Events (audit log)
This command only works for DRACOON Server and is not supported for DRACOON Cloud! For DRACOON Cloud, please use the built-in reports.
# lists first 500 events of your domain
dccmd-rs reports events your.dracoon.domain/
# list all events of your domain (will *not* parallelize and might take a long time to conclude!)
dccmd-rs reports events your.dracoon.domain/ --all
# list events as CSV format
dccmd-rs reports events your.dracoon.domain/ --csv > events.csv # store in CSV
# provide optional start date or end date
dccmd-rs reports events your.dracoon.domain/ --start-date 2021-01-01
dccmd-rs reports events your.dracoon.domain/ --end-date 2024-01-01
# filter by event status (failure: 2, success: 0)
dccmd-rs reports events your.dracoon.domain/ --status 0 # all success operations
# filter by user id (only display events from user 99)
dccmd-rs reports events your.dracoon.domain/ --user-id 99
# list eventlog operations (needed for filtering by operation id)
dccmd-rs reports operation-types your.dracoon.domain/
# filter by operation id (type)
dccmd-rs reports events your.dracoon.domain/ --operation-type 125
Permissions (node permissions)
This command only works for DRACOON Server and is not supported for DRACOON Cloud! For DRACOON Cloud, please use the built-in reports.
# list all permissions of your domain (will *not* parallelize and might take a long time to conclude!)
# note: if you call this, in order to reduce load, first, all users are fetched and then all permissions generated per user
# there is no pagination in this, so you can ommit offset and limit
dccmd-rs reports permissions your.dracoon.domain/
# list permissions as CSV format
dccmd-rs reports permissions your.dracoon.domain/ --csv > events.csv # store in CSV
# list permissions for a specific user
dccmd-rs reports permissions your.dracoon.domain/ --filter userId:eq:99
# list permissions for a specific room
dccmd-rs reports permissions your.dracoon.domain/ --filter nodeId:eq:99
# for a full list of available filters, check the API documentation
Config
Stored authorization
You can verify if the refresh stoken is (securely) stored via the config auth ls
command.
In order to remove a stored token, use the config auth rm
command.
# displays user info for stored refresh token
dccmd-rs config auth ls your.dracoon.domain/
# removes stored refresh token for given domain
dccmd-rs config auth rm your.dracoon.domain/
Stored crypto secret
You can verify if the crypto secret is (securely) stored via the config crypto ls
command.
In order to remove a stored token, use the config crypto rm
command.
# displays user info for stored crypto secret
dccmd-rs config crypto ls your.dracoon.domain/
# removes stored crypto secret for given domain
dccmd-rs config crypto rm your.dracoon.domain/
System info
You can fetch the system info (OpenID config, AD config, used users and storage) via the config system-info
command.
# displays system information
# requires config manager role
dccmd-rs config system-info your.dracoon.domain/
CLI mode
Currently dccmd-rs will fail to store credentials if you are running a headless Linux or are trying to run in Windows with WSL. In such cases you can pass the username and password as arguments like so:
dccmd-rs --username your_username --password your_secure_password ls your.dracoon.domain/some/path
Use this at your own risk and be aware that the password is stored in plain in your shell history. Note: This only works for the password flow - this means you must use a local user.
This also works for the encryption password like so:
dccmd-rs --username your_username --password your_secure_password --encryption-password your_secure_encryption_password ls your.dracoon.domain/some/path
Dependencies
~22–38MB
~605K SLoC