aspera-cli 4.27.5 → 4.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +8 -5
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +11 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +4 -1
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
data/README.md CHANGED
@@ -1,58 +1,135 @@
1
- # Aspera CLI
1
+ # IBM Aspera CLI
2
+
3
+ **The automation interface for IBM Aspera. From command line to AI agents.**
2
4
 
3
5
  [![Gem Version](https://badge.fury.io/rb/aspera-cli.svg)](https://badge.fury.io/rb/aspera-cli)
4
6
  [![unit tests](https://github.com/IBM/aspera-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/IBM/aspera-cli/actions)
7
+ [![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/IBM/aspera-cli/main/docs/coverage.json)](tests/README.md#coverage)
5
8
  [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
6
9
  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
7
10
 
8
- ![Hootput the Owl](docs/mascot.svg)
11
+ ![Hootput the Owl](docs/art/mascot.svg)
9
12
 
10
- **`ascli`** is the command-line interface for IBM Aspera products.
11
- Use it from the terminal or in scripts to:
13
+ **`ascli`** is an open-source toolkit to automate, integrate and operate IBM Aspera products.
14
+ Administrators, developers, integration engineers and AI agents use the same consistent interface to the whole Aspera ecosystem.
12
15
 
13
- - Drive **Aspera on Cloud**, **Faspex**, **Shares**, **Node**, **Console**, **Orchestrator**, and **High-Speed Transfer Server**
14
- - Call REST APIs and run high-speed transfers (**FASP**)
15
- - Automate workflows with config, presets, and scripting
16
+ ## What can you do with `ascli`?
16
17
 
17
- ## Documentation
18
+ - **Transfer**: run high-speed **FASP** transfers, with the transfer agent of your choice (`ascp`, Transfer Daemon, IBM Aspera for Desktop, HTTP Gateway, Node API).
19
+ - **Automate**: script transfers, packages, file management, administration and operational workflows.
20
+ - **Integrate**: call Aspera REST APIs as commands, with JSON, YAML, CSV or table output, filtered with JMESPath.
21
+ - **Operate**: Aspera on Cloud, Faspex, Shares, Node API, High-Speed Transfer Server, Console, Orchestrator, Cloud Object Storage.
22
+ - **Configure**: reusable presets per environment, secrets in a vault, never in scripts.
23
+ - **Diagnose**: analyze `ascp` logs to find why a transfer failed or is slow.
24
+ - **Use AI**: let AI assistants and agents operate Aspera, in a shell or through the MCP server, without seeing secrets.
18
25
 
19
- Choose what best suits you:
26
+ One interface, several ways to use it:
20
27
 
21
- | Resource | Link |
22
- | -------- | ---- |
23
- | **Online manual** | [GitHub docs/README.md](https://github.com/IBM/aspera-cli/blob/main/docs/README.md) |
24
- | **PDF manual** | In [GitHub Releases](https://github.com/IBM/aspera-cli/releases) |
25
- | **RubyGems** | [rubygems.org/gems/aspera-cli](https://rubygems.org/gems/aspera-cli) |
26
- | **RubyDoc** | [rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli) |
27
- | **Docsify** | [online](https://docsify-this.net/?basePath=https://raw.githubusercontent.com/IBM/aspera-cli/main/docs&homepage=README.md&sidebar=true&browser-tab-title=Aspera%20CLI%20Manual&hide-credits=true&maxLevel=4&externalLinkTarget=_blank&image-captions=true&dark-mode=auto) |
28
+ | Interface | Usage |
29
+ | --------- | ----- |
30
+ | Command line | Interactive administration and operations |
31
+ | Shell scripts, schedulers, CI/CD | Repeatable automation and batch processing |
32
+ | Structured output | Integration with applications, monitoring and pipelines |
33
+ | MCP server, agent skill | AI assistants and AI agents |
28
34
 
29
- ## Install
35
+ ## Get started
30
36
 
31
- Install **Ruby** ≥ 3.1
37
+ Install **Ruby** ≥ 3.3, then:
32
38
 
33
39
  ```bash
34
40
  gem install aspera-cli
35
- ascli config transferd install
41
+ ascli transferd install
42
+ ascli -v
36
43
  ```
37
44
 
38
45
  The second command installs the **FASP** transfer engine (`ascp`).
39
- For other install methods (single executable, Docker, Chocolatey, Homebrew), see the [user manual](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#installation).
46
+ No Ruby? Use the single executable, the Linux or Windows portable package, Chocolatey or the container image: see [Installation](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#installation).
47
+
48
+ ## Try it in 60 seconds
40
49
 
41
- **Quick check:**
50
+ No account needed: the public Aspera demo server is configured for you.
42
51
 
43
52
  ```bash
44
- ascli -v
53
+ ascli config initdemo
54
+ ascli server browse /
55
+ ascli server download /aspera-test-dir-small/10MB.1
45
56
  ```
46
57
 
58
+ ## Examples
59
+
60
+ ```bash
61
+ # Upload 1 GB of generated data (no local file needed), at 500 Mbps maximum
62
+ ascli server upload 'faux:///test1g?1g' --to-folder=/Upload --ts.target_rate=500m
63
+
64
+ # Browse files in Aspera on Cloud
65
+ ascli aoc files browse /
66
+
67
+ # List packages in Faspex 5, as JSON for a script
68
+ ascli faspex5 packages list --format=json
69
+
70
+ # Diagnose transfers from ascp log files
71
+ ascli config ascp logs diagnostics /var/log/aspera.log
72
+
73
+ # Let an AI assistant operate Aspera
74
+ ascli mcp server
75
+ ```
76
+
77
+ Each product has its own plugin (`aoc`, `faspex5`, `shares`, `node`, `server`, `console`, `orchestrator`, `cos`...).
78
+ `ascli <plugin> -h` lists its commands.
79
+
80
+ ## Use with AI assistants
81
+
82
+ `ascli` lets AI assistants and AI agents (LLM) operate IBM Aspera products for you, with the same commands, presets and secrets as you:
83
+
84
+ - **In a shell** (coding agents): nothing to set up. Give the agent [`llms.txt`](https://github.com/IBM/aspera-cli/blob/main/llms.txt), or install the agent skill [`skills/ascli`](https://github.com/IBM/aspera-cli/tree/main/skills/ascli) (with Claude Code: `/plugin install ascli --marketplace IBM/aspera-cli`): the agent then discovers commands, arguments and options by itself.
85
+ - **MCP server** (Model Context Protocol): `ascli mcp server` exposes all commands to any MCP client (IBM Bob, Claude, VS Code...), locally or over HTTPS with token or OAuth authentication.
86
+
87
+ Safe by default: in the MCP server, the AI can neither execute code nor write files where it chooses, and never sees secrets.
88
+ See [Leveraging AI Assistance](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#leveraging-ai-assistance) in the manual.
89
+
90
+ ## Supported products
91
+
92
+ | Product | Plugin | What you can do |
93
+ | ------- | ------ | --------------- |
94
+ | IBM Aspera on Cloud | `aoc` | Files, packages, administration, Automation workflows |
95
+ | IBM Aspera Faspex 5 | `faspex5` | Packages, shared inboxes, administration |
96
+ | IBM Aspera Shares | `shares` | Files, administration |
97
+ | IBM Aspera High-Speed Transfer Server | `server`, `node` | Transfers over SSH, Node API, access keys, `ascp` logs |
98
+ | IBM Aspera Console | `console` | Transfers, administration |
99
+ | IBM Aspera Orchestrator | `orchestrator` | Workflows, work orders, plugins |
100
+ | IBM Cloud Object Storage | `cos` | Transfers to buckets |
101
+ | IBM Aspera HTTP Gateway | `httpgw` | Transfer agent, health |
102
+ | IBM Aspera faspio Gateway | `faspio` | Bridges, health, metrics |
103
+ | IBM Aspera Transfer Daemon | `transferd` | Install, run as a service, manage transfers |
104
+
105
+ ## Documentation
106
+
107
+ | Resource | Link |
108
+ | -------- | ---- |
109
+ | **Documentation site** | [ibm.github.io/aspera-cli](https://ibm.github.io/aspera-cli/) (one page per section, [llms.txt](https://ibm.github.io/aspera-cli/llms.txt) for AI assistants) |
110
+ | **Online manual** | [GitHub docs/README.md](https://github.com/IBM/aspera-cli/blob/main/docs/README.md) |
111
+ | **PDF manual** | In [GitHub Releases](https://github.com/IBM/aspera-cli/releases) |
112
+ | **RubyGems** | [rubygems.org/gems/aspera-cli](https://rubygems.org/gems/aspera-cli) |
113
+ | **RubyDoc** | [rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli) |
114
+ | **Docsify** | [online](https://docsify-this.net/?basePath=https://raw.githubusercontent.com/IBM/aspera-cli/main/docs&homepage=README.md&sidebar=true&browser-tab-title=Aspera%20CLI%20Manual&hide-credits=true&maxLevel=4&externalLinkTarget=_blank&image-captions=true&dark-mode=auto) |
115
+
116
+ For debugging, use `--log-level=debug`.
117
+
118
+ ## Trust
119
+
120
+ `ascli` is used to operate production systems, so the project follows strict practices: [OpenSSF Best Practices](https://www.bestpractices.dev/projects/5861) silver badge, high test coverage, a [security assurance case](https://github.com/IBM/aspera-cli/blob/main/docs/ASSURANCE_CASE.md), and secrets kept out of commands and AI clients.
121
+ For security and compliance reviews, see [Security and Trust](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#security-and-trust) in the manual.
122
+
47
123
  ## Contributing
48
124
 
125
+ - **Questions, ideas, show and tell:** [GitHub Discussions](https://github.com/IBM/aspera-cli/discussions)
49
126
  - **Bugs & features:** [BUGS.md](https://github.com/IBM/aspera-cli/blob/main/BUGS.md)
127
+ - **Security vulnerabilities:** [SECURITY.md](https://github.com/IBM/aspera-cli/blob/main/SECURITY.md)
50
128
  - **How to contribute:** [CONTRIBUTING.md](https://github.com/IBM/aspera-cli/blob/main/CONTRIBUTING.md)
129
+ - **Code of conduct:** [CODE_OF_CONDUCT.md](https://github.com/IBM/aspera-cli/blob/main/CODE_OF_CONDUCT.md)
130
+ - **Governance:** [GOVERNANCE.md](https://github.com/IBM/aspera-cli/blob/main/GOVERNANCE.md)
51
131
  - **Release notes:** [CHANGELOG.md](https://github.com/IBM/aspera-cli/blob/main/CHANGELOG.md)
52
132
 
53
- Commands map to Aspera REST APIs; see the manual for options.
54
- For debugging, use `--log-level=debug`.
55
-
56
133
  ## License
57
134
 
58
- [Apache-2.0](https://github.com/IBM/aspera-cli/blob/main/LICENSE)
135
+ Open source, [Apache-2.0](https://github.com/IBM/aspera-cli/blob/main/LICENSE), by IBM.
data/SECURITY.md ADDED
@@ -0,0 +1,70 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ Security fixes are released in a new version of `aspera-cli`.
6
+ They are not back-ported to older versions.
7
+
8
+ | Version | Supported |
9
+ | -------------- | -------------------------------- |
10
+ | Latest release | ✅ |
11
+ | Older releases | ❌ Upgrade to the latest release |
12
+
13
+ Supported Ruby versions are listed in the manual: [Ruby](docs/README.md#ruby).
14
+
15
+ ## Reporting a Vulnerability
16
+
17
+ **Do not report a security vulnerability in a public GitHub issue, discussion or pull request.**
18
+
19
+ Report it privately on GitHub: [Report a vulnerability](https://github.com/IBM/aspera-cli/security/advisories/new).
20
+ For instructions, see [Privately reporting a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability).
21
+
22
+ Alternatively, report it to the IBM Product Security Incident Response Team (PSIRT) using one of the methods on the [IBM Trust Center](https://www.ibm.com/trust/security-psirt).
23
+
24
+ Include in the report:
25
+
26
+ - The `aspera-cli` version: `ascli -v`
27
+ - The Ruby version: `ruby -v`
28
+ - The operating system name and version
29
+ - The steps to reproduce, or a proof of concept
30
+ - The expected impact
31
+
32
+ Remove secrets (passwords, tokens, private keys) from logs and configuration files before you send them.
33
+
34
+ ## Scope
35
+
36
+ In scope: the Ruby gem `aspera-cli` (the `ascli` command), and how it interacts with IBM Aspera components.
37
+ See [Scope of Support](BUGS.md#scope-of-support).
38
+
39
+ Out of scope:
40
+
41
+ - Vulnerabilities in the IBM Aspera products themselves (`ascp`, Transfer SDK, High-Speed Transfer Server, Faspex, Shares, Console, Orchestrator, Aspera on Cloud) and in IBM Cloud Object Storage: report them to IBM PSIRT.
42
+ - A public CVE in a dependency gem that already has a fixed version: dependencies are updated with Renovate, and the update is included in the next release.
43
+
44
+ ## Trust Model
45
+
46
+ Trusted: the user account that runs `ascli`, its environment variables, and its configuration file and presets.
47
+ `ascli` restricts access to its configuration file to the current user, and can store secrets in a vault: see [Secret Vault](docs/README.md#secret-vault).
48
+
49
+ Commands and options are trusted only at security level `low`, the default: see [Security Level](docs/README.md#security-level).
50
+
51
+ - At level `low`, `ascli` can do anything that the user is allowed to do: features that execute code or access local files (for example `@ruby:`, `@file:`, plugins) work as designed.
52
+ - At levels `medium` and `high`, commands and options can come from an untrusted client, for example an MCP client.
53
+
54
+ `ascli` is not intended to be a public-facing web server.
55
+ The web servers that some commands start listen on a loopback address by default, and refuse to listen on another address without their protection: see [Web service](docs/README.md#web-service).
56
+
57
+ In scope:
58
+
59
+ - At levels `medium` and `high`: a command or option that bypasses the restrictions of the level, for example to read a file outside `allowed_paths`, write a file outside `writable_paths`, execute code, or reveal a secret.
60
+ - At any level: an issue that a party other than the local user can exploit, for example through a server response, a file received in a transfer, or a position on the network path when TLS certificate verification is enabled.
61
+
62
+ Out of scope:
63
+
64
+ - A feature that works as designed at level `low`.
65
+ - An issue that requires the user to disable a protection, for example `--insecure=yes`.
66
+ - A web server of `ascli` exposed to users or networks that are not trusted, without the protection of its command, or with HTTP instead of HTTPS on a network.
67
+
68
+ ## Assurance Case
69
+
70
+ The security requirements, the threat model, the trust boundaries, and the weaknesses countered are described in [docs/ASSURANCE_CASE.md](docs/ASSURANCE_CASE.md).
data/bin/ascli CHANGED
@@ -1,6 +1,9 @@
1
1
  #!/usr/bin/env ruby
2
2
  # frozen_string_literal: true
3
3
 
4
+ # SPDX-FileCopyrightText: IBM Corp.
5
+ # SPDX-License-Identifier: Apache-2.0
6
+
4
7
  # This is the main script to execute the Aspera CLI
5
8
 
6
9
  old_verbose = $VERBOSE
@@ -12,9 +15,9 @@ Encoding.default_external = Encoding::UTF_8
12
15
  $VERBOSE = old_verbose
13
16
 
14
17
  # start coverage (if enabled) before any library is loaded
15
- require 'aspera/coverage'
16
- require 'aspera/log'
17
- require 'aspera/cli/info'
18
+ require_relative '../lib/aspera/coverage'
19
+ require_relative '../lib/aspera/log'
20
+ require_relative '../lib/aspera/cli/info'
18
21
 
19
22
  # Early debug for parser
20
23
  # Note: does not accept short option names, nor extended values
@@ -31,8 +34,8 @@ rescue => e
31
34
  Process.exit(1)
32
35
  end
33
36
 
34
- require 'aspera/environment'
35
- require 'aspera/cli/runner'
37
+ require_relative '../lib/aspera/environment'
38
+ require_relative '../lib/aspera/cli/runner'
36
39
  Aspera::Environment.instance.fix_home
37
40
  Aspera::Environment.instance.fix_ca_certificates
38
41
  Aspera::Cli::Runner.new(ARGV).run
data/bin/asession CHANGED
@@ -1,12 +1,15 @@
1
1
  #!/usr/bin/env ruby
2
2
  # frozen_string_literal: true
3
3
 
4
- require 'aspera/coverage'
5
- require 'aspera/agent/direct'
6
- require 'aspera/cli/extended_value'
7
- require 'aspera/products/transferd'
8
- require 'aspera/log'
9
- require 'aspera/assert'
4
+ # SPDX-FileCopyrightText: IBM Corp.
5
+ # SPDX-License-Identifier: Apache-2.0
6
+
7
+ require_relative '../lib/aspera/coverage'
8
+ require_relative '../lib/aspera/agent/direct'
9
+ require_relative '../lib/aspera/cli/extended_value'
10
+ require_relative '../lib/aspera/products/transferd'
11
+ require_relative '../lib/aspera/log'
12
+ require_relative '../lib/aspera/assert'
10
13
  require 'json'
11
14
 
12
15
  class UsageError < StandardError; end
@@ -26,7 +29,7 @@ class SimpleTransferManager
26
29
  # Default SDK location
27
30
  SDK_DEFAULT_DIR = File.join(Dir.home, '.aspera', 'sdk')
28
31
  # Place transfer spec in that
29
- SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera"'
32
+ SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"<PASSWORD>"'
30
33
  SAMPLE_DEMO2 = '"direction":"receive","destination_root":"./test.dir"'
31
34
  STDIN_INPUT = '@json:@stdin:'
32
35
  class << self