{"id":16993620,"url":"https://github.com/unbekanntes-pferd/dccmd-rs","last_synced_at":"2025-04-12T04:50:56.439Z","repository":{"id":158940555,"uuid":"608820587","full_name":"unbekanntes-pferd/dccmd-rs","owner":"unbekanntes-pferd","description":"dccmd-rs (DRACOON Commander) – a CLI client for DRACOON (https://dracoon.com) written in Rust","archived":false,"fork":false,"pushed_at":"2025-01-29T06:23:30.000Z","size":2913,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T00:22:57.225Z","etag":null,"topics":["cli","client","dracoon","encryption","rust","s3"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unbekanntes-pferd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-02T20:02:49.000Z","updated_at":"2024-11-27T13:22:34.000Z","dependencies_parsed_at":"2023-07-09T02:19:06.299Z","dependency_job_id":"90e24076-a5bf-42c6-af10-5aee16916437","html_url":"https://github.com/unbekanntes-pferd/dccmd-rs","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unbekanntes-pferd","download_url":"https://codeload.github.com/unbekanntes-pferd/dccmd-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519473,"owners_count":21117757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","client","dracoon","encryption","rust","s3"],"created_at":"2024-10-14T03:43:37.083Z","updated_at":"2025-04-12T04:50:56.406Z","avatar_url":"https://github.com/unbekanntes-pferd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DRACOON Commander RS\n\n## What is this?\nThis is a port of [DRACOON Commander](https://github.com/unbekanntes-pferd/dccmd) - initially a Python3 project to use DRACOON via CLI.\nThe project serves as a demo client implementation using `dco3` - an API wrapper in Rust for DRACOON. \n\n### Built with\nThis project makes use of several awesome crates and uses async Rust throughout the project.\n\nCrates used:\n- [reqwest](https://crates.io/crates/reqwest)\n- [clap](https://crates.io/crates/clap)\n- [console](https://crates.io/crates/console)\n- [dialoguer](https://crates.io/crates/dialoguer)\n- [indicatif](https://crates.io/crates/indicatif)\n\nFull dependency list: [Cargo.toml](Cargo.toml)\n\nFor all DRACOON operations `dco3` is used.\n\n- [dco3](https://github.com/unbekanntes-pferd/dco3)\n\n## Installation\n\n### Regular installation\n\nYou can download precompiled binaries on the Github releases page: \n[Releases](https://github.com/unbekanntes-pferd/dccmd-rs/releases)\n\n**Note**: The `DRACOON Commander` OAuth app must be enabled in the DRACOON OAuth Apps settings.\n\n### Rust toolchain\n\nClone the repository and either use `cargo run` or build your own executable with `cargo build`:\n\n```bash\ngit clone https://github.com/unbekanntes-pferd/dccmd-rs.git\ncd dccmd-rs\ncargo build\n```\n\n**Note**: In order to build the client you need to set the following environment variables:\n\n```bash\nexport DCCMD_CLIENT_ID=your_client_id\nexport DCCMD_CLIENT_SECRET=your_client_secret\n```\nYou will also need to create a custom OAuth app in order for this to work.\n\n## What works?\n\nCurrently, the following commands are working:\n\n- `config` - config management of DRACOON Commander (see subcommands below)\n- `download` - downloads a file or folder / room from DRACOON to a desired location on disk (encrypted, unencrypted)\n- `upload` - uploads a file or folder to a parent in DRACOON (encrypted, unencrypted)\n- `ls` - lists all nodes for a given path in DRACOON\n- `mkdir` - creates a folder in given path in DRACOON\n- `mkroom` - creates a room (inherits permissions) in given path in DRACOON\n- `rm` - removes a node by given path in DRACOON\n- `cp` - copies node(s) by given path (or search) in DRACOON\n- `users` - user management in DRACOON (see subcommands below)\n- `groups` - group management in DRACOON (see subcommands below)\n- `reports` - DRACOON Server specific reports \n\n\n## Example usage\n\nFor the sake of clarity, the usage of the binary is called `dccmd-rs`, regardless of the use via `cargo` or a compiled executable.\n\n### Downloads\n\n![dccmd-rs ls](./assets/dccmd-download-0.8.0.gif)\n\nTo download a file, use the download command:\n\n```bash\ndccmd-rs download your.dracoon.domain/some/room/some-file.pdf ./your/path/your-name.pdf\n```\n\nTo download a container (room or folder), use the download command with recursive flag:\n\n```bash\ndccmd-rs download -r your.dracoon.domain/some/room ./your/path\n```\n**Note**: This will create a directory with same name as your container. Sub rooms are **not** included.\n\nTo download a list search result, use the download command with a search string:\n\n```bash\ndccmd-rs download your.dracoon.domain/some/*.pdf ./your/path\n```\n\nTo download a file with **no** authorization to a public download share (share):\n\n```bash\ndccmd-rs download your.dracoon.domain/public/download-shares/someLongAccessKey /your/path\n```\n\n**Note**: This essentially means you need to copy the created share link\n\n### Uploads\n\n![dccmd-rs ls](./assets/dccmd-upload-0.8.0.gif)\n\nTo upload a file, use the upload command:\n\n```bash\ndccmd-rs upload ./your/path/your-name.pdf your.dracoon.domain/some/room\n```\n\n**Note:** Currently, providing a custom name is not implemented.\n\nYou can share the file directly and create a share link (default settings) by passing the `--share` flag:\n\n```bash\ndccmd-rs upload ./your/path/your-name.pdf your.dracoon.domain/some/room --share\n```\n\nTo upload a folder, use the `--recursive` flag:\n\n```bash\ndccmd-rs upload /your/path your.dracoon.domain/some/room\n```\n**Note:** Currently only absolute paths are supported for recursive uploads.\n\nTo upload a file with **no** authorization to a public upload share (file request):\n\n```bash\ndccmd-rs upload /your/path your.dracoon.domain/public/upload-shares/someLongAccessKey\n```\n\n**Note**: This essentially means you need to copy the created share link\n\n#### Upload options\n\nWhen 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`).\n\nIn order to change this behavior, you can the pass the following flags / options:\n- *--overwrite* - a file with the same name will be overwritten (essentially creating versions of the same file)\n- *--keep-share-links* - if *--overwrite* is used, you can additionally keep existing (download) share links for file(s)\n\n ### Transfers\n\n To transfer a file from DRACOON instance another instance, use the transfer command:\n\n```bash\ndccmd-rs transfer instance1.domain.com/some/file.pdf instance2.domain.com/some/target/path\n```\n\n### Transfer options\nThese options are analogue to the upload options (see above).\n\nWhen 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`).\n\nIn order to change this behavior, you can the pass the following flags / options:\n- *--overwrite* - a file with the same name will be overwritten (essentially creating versions of the same file)\n- *--keep-share-links* - if *--overwrite* is used, you can additionally keep existing (download) share links for file(s)\n\n\n### Listing nodes\n\n![dccmd-rs ls](./assets/dccmd-ls-0.7.0.gif)\n\nTo list nodes, use the `ls` command:\n\n```bash\ndccmd-rs ls your.dracoon.domain/some/path\n\n// for root node use a trailing slash\ndccmd-rs ls your.dracoon.domain/\n\n// for searches within the room\ndccmd-rs ls your.dracoon.domain/*.pdf \n\n// only files\ndccmd-rs ls your.dracoon.domain/some/room --filter type:eq:file\n```\n\nOptions:\n - `-l`, `--long` - prints all details (size, updated by, node id...)           \n - `-r`, `--human-readable` - prints size in human readable format\n -    `--managed` - shows room as room admin / room manager (rooms w/o permissions)       \n -    `--all` - fetches all items (default: first 500 items)\n - `--filter` - filter for specific values (see API docs for filter info)\n\n\n### Deleting nodes\n\nTo delete nodes, use the `rm` command:\n\n```bash\ndccmd-rs rm your.dracoon.domain/some/path/some_file.pdf\ndccmd-rs rm -r your.dracoon.domain/some/path/some/room\ndccmd-rs rm -r your.dracoon.domain/*test\n```\n*Note*: If you intend to delete a container (room or folder), use the recursive flag.\n*Note*: Room deletion always requires additional confirmation.\n*Note*: You can delete the content in a room by using search strings (`*` deletes all). This does **not** include rooms.\n\n### Creating folders\n\nTo create folders, use the `mkdir` command:\n\n```bash\ndccmd-rs mkdir your.dracoon.domain/some/path/newfolder\n```\n\nTo create rooms, use the `mkroom` command:\n\n```bash\ndccmd-rs mkroom your.dracoon.domain/some/path/newroom\n# pass optional usernames for admins (example adds admins with usernames foo1, foo2 and foo3)\ndccmd-rs mkroom your.dracoon.domain/some/path/newroom -a foo1 -a foo2 -a foo3\n\n# you can additionally inherit permissions using the --inherit-permissions flag \ndccmd-rs mkroom your.dracoon.domain/some/path/newroom -a foo1 --inherit-permissions\n\n# you can also set the default classification (example sets to confidential)\ndccmd-rs mkroom your.dracoon.domain/some/path/newroom --classification 3\n```\n\n### Copying nodes\n\nTo copy nodes, use the `cp` command:\n\n```bash\ndccmd-rs cp your.dracoon.domain/some/path /other/path/new/target\n\n# you can pass a search to copy e.g. only csv files\ndccmd-rs cp \"your.dracoon.domain/some/path/*.csv\" /other/path/new/target\n\n# note: if you need to copy to another instance, use *transfer* instead of *cp* \n# in that case, the full path is required\n```\n\n\n\n### Managing users\n\nTo import users, you can use the `users import some.dracoon.domain.com` command:\n\n```bash\n# csv header must be 'first_name,last_name,email,login,oidc_id,mfa_enforced'\n# the order of these fields does not matter\n# login, oidc_id and mfa_enforced are optional but must be present as field\ndccmd-rs users import your.dracoon.domain/ /path/to/users.csv\ndccmd-rs users import your.dracoon.domain/ /path/to/users.csv --oidc-id 2 # import as OIDC users\n```\n\nTo list users, you can use the `users ls some.dracoon.domain.com` command:\n\n```bash\n# optional flags: --all (lists all users, default: 500, paging) --csv (csv format)\n# optional flags: --filter (see API docs for filter info)\ndccmd-rs users ls your.dracoon.domain/\ndccmd-rs users ls your.dracoon.domain/ --csv --all \u003e userlist.csv\ndccmd-rs users ls your.dracoon.domain/ --filter userName:cn:foo\n```\n\nTo create users, you can use the `users create some.dracoon.domain.com` command:\n\n```bash\n# params: --first-name, --last-name, --email, --login, --oidc-id \ndccmd-rs users create your.dracoon.domain/ -f foo -l bar -e foo@bar.com # local user\ndccmd-rs users create your.dracoon.domain/ -f foo -l bar -e foo@bar.com --oidc-id 2 # OIDC user\n```\n\nTo invite guest users, you can use the `users invite some.dracoon.domain.com/some/room/or/folder` command:\n\n```bash\n# params: --first-name, --last-name, --email\ndccmd-rs users invite your.dracoon.domain/some/room -f foo -l bar -e foo@bar.com\n# if you provide a folder, you invite into the corresponding parent room\ndccmd-rs users invite your.dracoon.domain/some/room/folder -f foo -l bar -e foo@bar.com\n```\n\nTo delete users, you can use the `users some.dracoon.domain.com rm` command:\n\n```bash\n# supported: user id, user login / username\ndccmd-rs users rm your.dracoon.domain/ --user-id 2\ndccmd-rs users rm your.dracoon.domain/ --user-name foo # short: -u\n```\n\nTo fetch specific user info, you can use the `users info some.dracoon.domain.com` command:\n\n```bash\n# supported: user id, user login / username\ndccmd-rs users info your.dracoon.domain/ --user-id 2\ndccmd-rs users info your.dracoon.domain/ --user-name foo # short: -u\n```\n\n#### Switch auth methods\n\nYou can switch the auth method for a specific subset (or all users) belonging to a current auth method.\nIn order to use it, you need to pass the following parameters:\n- *current-method* - current auth method in DRACOON - valid options: basic (or local), openid (or oidc), active-directory (or ad)\n- *new-method* - new auth method in DRACOON - valid options see above\n- *current-oidc-id* - optional current OIDC config id - must be provided if current method is openid\n- *new-oidc-id* - optional new OIDC config id - must be provided if new method is openid\n- *current-ad-id* - optional current AD config id - must be provided if current method is active-directory\n- *new-ad-id* - optional new AD config id - must be provided if new method is active-directory\n- *filter* - optional user filter - see API docs for details (e.g. email:cn:somedomain.com)\n- *login* - optional login transformation (e.g. email, username, firstname.lastname) default: email\n\n```bash\n# in order to identify AD or openid ids, use the config system-info command (see below)\n\n# switch from basic auth (local) to openid if local user email contains somedomain.com\ndccmd-rs users switch-auth --current-method basic --new-method openid --new-oidc-id 99 --filter email:cn:somedomain.com your.dracoon.domain/\n\n# switch from openid with id 88 to openid with id 99 while setting the login as firstname.lastname (replaced by user values)\ndccmd-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\"\n```\n\n#### Enforce MFA (multi-factor authentication)\nIn order to enforce MFA for a subset of users, you can (e.g. periodically) run the following commands:\n\n```bash\n# enforce only for local users \ndccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local\n# enforce only for local users with specific filter (for filter details see API docs)\ndccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local --filter email:cn:somedomain.com\n# enforce only for a given filter\ndccmd-rs users enforce-mfa your.dracoon.domain/ --filter userName:cn:testuser\n# enforce for a specific group id (list groups via groups ls command for id)\ndccmd-rs users enforce-mfa your.dracoon.domain/ --group-id 99\n# combine all: all local users in group 99 with somedomain.com in email\ndccmd-rs users enforce-mfa your.dracoon.domain/ --auth-method local --group-id 99 --filter email:cn:somedomain.com\n```\n\n### Managing groups\n\nTo list groups, you can use the `groups ls some.dracoon.domain.com` command:\n\n```bash\n# optional flags: --all (lists all groups, default: 500, paging) --csv (csv format)\n# optional flags: --filter (see API docs for filter info)\ndccmd-rs groups ls your.dracoon.domain/\ndccmd-rs groups ls your.dracoon.domain/ --csv --all \u003e grouplist.csv\ndccmd-rs groups ls your.dracoon.domain/ --filter name:eq:foo\n```\n\nTo create groups, you can use the `groups create some.dracoon.domain.com` command:\n\n```bash\n# params: --name\ndccmd-rs groups create your.dracoon.domain/ --name foo\n```\n\nTo delete groups, you can use the `groups some.dracoon.domain.com rm` command:\n\n```bash\n# supported: group id, group name\ndccmd-rs groups rm your.dracoon.domain/ --group-id 2\ndccmd-rs groups rm your.dracoon.domain/ --group-name foo\n```\n\n### Group users\n\nTo list group users, you can use the `groups users ls some.dracoon.domain.com` command:\n\n```bash\n# get all group users for every group\ndccmd-rs groups users ls your.dracoon.domain/\n\n# list group users in csv format \ndccmd-rs groups users ls your.dracoon.domain/ --csv\ndccmd-rs groups users ls your.dracoon.domain/ --csv --all \u003e groupusers.csv\n\n# get specific group users (for a group)\ndccmd-rs groups users ls your.dracoon.domain/YourGroupName --csv --all\n```\n\n### Reports\n\nTo fetch reports (either table live view or CSV) of events or permissions, use the respective `reports` command:\n\n#### Events (audit log)\n**This command only works for DRACOON Server and is not supported for DRACOON Cloud!**\nFor DRACOON Cloud, please use the built-in reports.\n\n```bash\n# lists first 500 events of your domain\ndccmd-rs reports events your.dracoon.domain/ \n# list all events of your domain (will *not* parallelize and might take a long time to conclude!)\ndccmd-rs reports events your.dracoon.domain/ --all\n# list events as CSV format\ndccmd-rs reports events your.dracoon.domain/ --csv \u003e events.csv # store in CSV\n\n# provide optional start date or end date\ndccmd-rs reports events your.dracoon.domain/ --start-date 2021-01-01\ndccmd-rs reports events your.dracoon.domain/ --end-date 2024-01-01\n\n# filter by event status (failure: 2, success: 0)\ndccmd-rs reports events your.dracoon.domain/ --status 0 # all success operations\n\n# filter by user id (only display events from user 99)\ndccmd-rs reports events your.dracoon.domain/ --user-id 99\n\n# list eventlog operations (needed for filtering by operation id)\ndccmd-rs reports operation-types your.dracoon.domain/\n\n# filter by operation id (type) \ndccmd-rs reports events your.dracoon.domain/ --operation-type 125\n```\n\n#### Permissions (node permissions)\n**This command only works for DRACOON Server and is not supported for DRACOON Cloud!**\nFor DRACOON Cloud, please use the built-in reports.\n\n```bash\n# list all permissions of your domain (will *not* parallelize and might take a long time to conclude!)\n# note: if you call this, in order to reduce load, first, all users are fetched and then all permissions generated per user\n# there is no pagination in this, so you can ommit offset and limit\ndccmd-rs reports permissions your.dracoon.domain/ \n# list permissions as CSV format\ndccmd-rs reports permissions your.dracoon.domain/ --csv \u003e events.csv # store in CSV\n\n# list permissions for a specific user\ndccmd-rs reports permissions your.dracoon.domain/ --filter userId:eq:99\n\n# list permissions for a specific room\ndccmd-rs reports permissions your.dracoon.domain/ --filter nodeId:eq:99\n# for a full list of available filters, check the API documentation\n```\n\n### Config\n\n#### Stored authorization\n\nYou can verify if the refresh stoken is (securely) stored via the `config auth ls` command.\nIn order to remove a stored token, use the `config auth rm` command.\n\n```bash\n# displays user info for stored refresh token\ndccmd-rs config auth ls your.dracoon.domain/\n# removes stored refresh token for given domain\ndccmd-rs config auth rm your.dracoon.domain/ \n```\n\n#### Stored crypto secret\n\nYou can verify if the crypto secret is (securely) stored via the `config crypto ls` command.\nIn order to remove a stored token, use the `config crypto rm` command.\n\n```bash\n# displays user info for stored crypto secret\ndccmd-rs config crypto ls your.dracoon.domain/\n# removes stored crypto secret for given domain\ndccmd-rs config crypto rm your.dracoon.domain/ \n```\n\n#### System info\n\nYou can fetch the system info (OpenID config, AD config, used users and storage) via the `config system-info` command.\n\n```bash\n# displays system information\n# requires config manager role\ndccmd-rs config system-info your.dracoon.domain/\n```\n\n\n### CLI mode\n\nCurrently dccmd-rs will fail to store credentials if you are running a headless Linux or are trying to run in Windows with WSL.\nIn such cases you can pass the username and password as arguments like so:\n\n```bash\ndccmd-rs --username your_username --password your_secure_password ls your.dracoon.domain/some/path\n```\n\nUse this at your own risk and be aware that the password is stored in plain in your shell history.\n*Note*: This only works for the password flow - this means you **must** use a local user. \n\nThis also works for the encryption password like so: \n\n```bash\ndccmd-rs --username your_username --password your_secure_password --encryption-password your_secure_encryption_password ls your.dracoon.domain/some/path\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbekanntes-pferd%2Fdccmd-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funbekanntes-pferd%2Fdccmd-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbekanntes-pferd%2Fdccmd-rs/lists"}