aspera-cli 4.28.0 → 4.29.1

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 (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  14. data/docs/test-mcp-with-ai.md +8 -8
  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 +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  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 +7 -4
  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 +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  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 +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  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 +16 -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 +17 -2
  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 +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
data/README.md CHANGED
@@ -1,58 +1,154 @@
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.2
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).
40
47
 
41
- **Quick check:**
48
+ ## Try it in 60 seconds
49
+
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
56
+ ```
57
+
58
+ Watch it first: [IBM Aspera in 60 seconds](https://youtu.be/TBf1W1mmX0A) (video, 1 min 23 s), more demos on the [Aspera CLI YouTube channel](https://www.youtube.com/@AsperaCLI).
59
+
60
+ ## Examples
61
+
62
+ ```bash
63
+ # Upload 1 GB of generated data (no local file needed), at 500 Mbps maximum
64
+ ascli server upload 'faux:///test1g?1g' --to-folder=/Upload --ts.target_rate=500m
65
+
66
+ # Browse files in Aspera on Cloud
67
+ ascli aoc files browse /
68
+
69
+ # List packages in Faspex 5, as JSON for a script
70
+ ascli faspex5 packages list --format=json
71
+
72
+ # Diagnose transfers from ascp log files
73
+ ascli config ascp logs diagnostics /var/log/aspera.log
74
+
75
+ # Let an AI assistant operate Aspera
76
+ ascli mcp server
77
+ ```
78
+
79
+ Each product has its own plugin (`aoc`, `faspex5`, `shares`, `node`, `server`, `console`, `orchestrator`, `cos`...).
80
+ `ascli <plugin> -h` lists its commands.
81
+
82
+ ## Use with AI assistants
83
+
84
+ `ascli` lets AI assistants and AI agents (LLM) operate IBM Aspera products for you, with the same commands, presets and secrets as you:
85
+
86
+ - **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 marketplace add IBM/aspera-cli`, then `/plugin install ascli@aspera-cli`): the agent then discovers commands, arguments and options by itself.
87
+ - **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.
88
+
89
+ MCP server setup: install the optional gem `mcp` with `ascli` (and `rack` for HTTPS), then declare the server in the MCP client (local, `stdio`):
90
+
91
+ ```bash
92
+ gem install aspera-cli mcp
45
93
  ```
46
94
 
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "ascli": {
99
+ "command": "ascli",
100
+ "args": ["mcp", "server"]
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ Safe by default: in the MCP server, the AI can neither execute code nor write files where it chooses, and never sees secrets.
107
+ See [Leveraging AI Assistance](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#leveraging-ai-assistance) in the manual.
108
+
109
+ ## Supported products
110
+
111
+ | Product | Plugin | What you can do |
112
+ | ------- | ------ | --------------- |
113
+ | IBM Aspera on Cloud | `aoc` | Files, packages, administration, Automation workflows |
114
+ | IBM Aspera Faspex 5 | `faspex5` | Packages, shared inboxes, administration |
115
+ | IBM Aspera Shares | `shares` | Files, administration |
116
+ | IBM Aspera High-Speed Transfer Server | `server`, `node` | Transfers over SSH, Node API, access keys, `ascp` logs |
117
+ | IBM Aspera Console | `console` | Transfers, administration |
118
+ | IBM Aspera Orchestrator | `orchestrator` | Workflows, work orders, plugins |
119
+ | IBM Cloud Object Storage | `cos` | Transfers to buckets |
120
+ | IBM Aspera HTTP Gateway | `httpgw` | Transfer agent, health |
121
+ | IBM Aspera faspio Gateway | `faspio` | Bridges, health, metrics |
122
+ | IBM Aspera Transfer Daemon | `transferd` | Install, run as a service, manage transfers |
123
+
124
+ ## Documentation
125
+
126
+ | Resource | Link |
127
+ | -------- | ---- |
128
+ | **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) |
129
+ | **Online manual** | [GitHub docs/README.md](https://github.com/IBM/aspera-cli/blob/main/docs/README.md) |
130
+ | **PDF manual** | In [GitHub Releases](https://github.com/IBM/aspera-cli/releases) |
131
+ | **RubyGems** | [rubygems.org/gems/aspera-cli](https://rubygems.org/gems/aspera-cli) |
132
+ | **RubyDoc** | [rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli) |
133
+ | **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) |
134
+
135
+ For debugging, use `--log-level=debug`.
136
+
137
+ ## Trust
138
+
139
+ `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.
140
+ 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.
141
+
47
142
  ## Contributing
48
143
 
144
+ - **Questions, ideas, show and tell:** [GitHub Discussions](https://github.com/IBM/aspera-cli/discussions)
49
145
  - **Bugs & features:** [BUGS.md](https://github.com/IBM/aspera-cli/blob/main/BUGS.md)
146
+ - **Security vulnerabilities:** [SECURITY.md](https://github.com/IBM/aspera-cli/blob/main/SECURITY.md)
50
147
  - **How to contribute:** [CONTRIBUTING.md](https://github.com/IBM/aspera-cli/blob/main/CONTRIBUTING.md)
148
+ - **Code of conduct:** [CODE_OF_CONDUCT.md](https://github.com/IBM/aspera-cli/blob/main/CODE_OF_CONDUCT.md)
149
+ - **Governance:** [GOVERNANCE.md](https://github.com/IBM/aspera-cli/blob/main/GOVERNANCE.md)
51
150
  - **Release notes:** [CHANGELOG.md](https://github.com/IBM/aspera-cli/blob/main/CHANGELOG.md)
52
151
 
53
- Commands map to Aspera REST APIs; see the manual for options.
54
- For debugging, use `--log-level=debug`.
55
-
56
152
  ## License
57
153
 
58
- [Apache-2.0](https://github.com/IBM/aspera-cli/blob/main/LICENSE)
154
+ Open source, [Apache-2.0](https://github.com/IBM/aspera-cli/blob/main/LICENSE), by IBM.
data/SECURITY.md ADDED
@@ -0,0 +1,84 @@
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
+ ## Response Process
35
+
36
+ 1. The report is acknowledged within 14 days.
37
+ 2. It is assessed with the [Scope](#scope) and the [Trust Model](#trust-model): the reporter is told whether it is accepted, and why if it is not.
38
+ 3. An accepted vulnerability is fixed in the next release, see [Supported Versions](#supported-versions).
39
+ The reporter is asked not to disclose it before this release.
40
+ 4. The release notes ([CHANGELOG.md](CHANGELOG.md)) describe the fix in section "Issues Fixed", with the CVE identifier when one is assigned.
41
+ They credit the reporter, with the name the reporter chooses, unless the reporter asks to remain anonymous.
42
+ 5. Disclosure:
43
+ - A report sent on GitHub is handled in a private GitHub security advisory.
44
+ After the release, the advisory is published with the fixed version, so that it is in the [GitHub Advisory Database](https://github.com/advisories).
45
+ - A report sent to IBM PSIRT is disclosed by IBM PSIRT (CVE, security bulletin).
46
+ A GitHub security advisory is published with the same information.
47
+
48
+ ## Scope
49
+
50
+ In scope: the Ruby gem `aspera-cli` (the `ascli` command), and how it interacts with IBM Aspera components.
51
+ See [Scope of Support](BUGS.md#scope-of-support).
52
+
53
+ Out of scope:
54
+
55
+ - 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.
56
+ - 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.
57
+
58
+ ## Trust Model
59
+
60
+ Trusted: the user account that runs `ascli`, its environment variables, and its configuration file and presets.
61
+ `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).
62
+
63
+ Commands and options are trusted only at security level `low`, the default: see [Security Level](docs/README.md#security-level).
64
+
65
+ - 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.
66
+ - At levels `medium` and `high`, commands and options can come from an untrusted client, for example an MCP client.
67
+
68
+ `ascli` is not intended to be a public-facing web server.
69
+ 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).
70
+
71
+ In scope:
72
+
73
+ - 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.
74
+ - 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.
75
+
76
+ Out of scope:
77
+
78
+ - A feature that works as designed at level `low`.
79
+ - An issue that requires the user to disable a protection, for example `--insecure=yes`.
80
+ - 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.
81
+
82
+ ## Assurance Case
83
+
84
+ 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