FoD: Decide on command structure for managing scans

[rsenden]

As discussed internally, below are some potential candidates, based on current fcli fod <entity> <action> convention.

1. Generic entities, scan type in <action>

• fcli fod scan start-sast / start-dast
• fcli fod scan list (list all scans for release, filtering options to return only SAST scans for example)
• fcli fod scan wait-for <sast/dast/mobile scan id>
• fcli fod scan-config setup-sast / setup-dast / get-sast / get-dast
• fcli fod scan-results import-sast / download-sast / download-oss

Advantages:

• Clear what ‘entity’ we’re operating on and what type of data is returned (scan data vs scan configuration data for example)
• We can have generic commands that operate on all scan types, like scan wait-for or scan list

Disadvantages:

• Commands for single scan type are spread throughout multiple generic entities (scan, scan-config, …)
• Some future commands may not fit well in this structure because particular entities are only applicable for a single scan type (i.e., where would commands for importing DAST macro’s / Postman collections fit in this structure, or commands for generating SAST package)

2. Merge all scan-type specific commands into single -scan entity

• fcli fod sast-scan start / list / wait-for / setup / get-config / import-fpr / download-fpr
• fcli fod oss-scan import-sbom / download-sbom

Advantages:

• All SAST-related commands organized in single entity
• Easy to add commands that are applicable for only a single scan type / no need to think of where to put certain SAST-related commands

Disadvantages:

• Need to duplicate generic commands like wait-for
• No good place to list all scans for a release
• Long list of sast-scan <action> sub-commands
• Different commands output different data (scan data vs scan configuration data for example) which has some technical consequences and makes it more difficult in automation scenarios to understand what data/properties are returned by a particular command
• Not clear which command combinations are allowed (for example, can wait-for only be combined with start or also with import)

3. Have multiple entities for each scan type

• fcli fod sast-scan start / list/ wait-for
• fcli fod sast-config setup / get
• fcli fod sast-results import-fpr / download-fpr
• fcli fod oss-results import-sbom / download-sbom

Advantages:

• Clear what ‘entity’ we’re operating on (similar to option 1)
• All SAST-related commands can be easily found (contrary to option 1, somewhat similar to option 2)

Disadvantages:

• Need to duplicate generic commands like wait-for
• No good place to list all scans for release
• May lead to fairly long list of subcommands in fcli fod -h
• Potentially longer entity names (i.e., should we have sast-config or sast-scan-config to be precise?)

4. Introduce fcli <module> [group] <entity> <action> concept

• fcli fod sast scan start / wait-for
• fcli fod sast config setup / get
• fcli fod sast results import / download-fpr
• fcli fod oss results import-sbom / download-sbom

Advantages:

• Similar to option 3, less sub-commands listed under fcli fod -h

Disadvantages:

• Similar to option 3
• Deviates from current fcli conventions
• Inconsistent command depth (3 levels in fcli fod release list vs 4 levels in fcli fod sast scan list)
• Users need to navigate through additional level of usage instructions

[bananegit]

Conventions aside I would prefer option 4. From the other ones I would prefer option 2, since everything is in one place. A generic list-scans command could be provided in the release module (e.g. fcli fod release list-scans).

[MikeTheSnowman]

My vote is with option 2. Here are my (possibly very flawed) justifications as rebuttles to the disadvantages mentioned:

• If there was a hierarchy of importance, I think that the <product> <entity> <action> is more important than avoiding duplicate commands (eg: duplicate wait-for)
• Need to duplicate generic commands like wait-for
  • I'll address this issue together with the last issue
• No good place to list all scans for a release
  • [response] Valid issue, and I too would want to avoid adding a list-scans command to the release entity. Though most of the time, I think most customers will be thinking about listing all SAST, SCA (OSS), DAST, or MAST scans for a release, rather than thinking of getting a full list of all scans (regardless of scan type). Again, I'm just thinking about what I believe will be the most common use case here.
• Long list of sast-scan sub-commands
  • I'm not sure if I agree with this. Off the top of my head, I think we're looking at 8 commands initially, which personally, I don't think is very long. But that's just my personaly opinion. But I do see the potential in the future for the number of commands to increase.
• Different commands output different data (scan data vs scan configuration data for example) which has some technical consequences and makes it more difficult in automation scenarios to understand what data/properties are returned by a particular command.
  • I'll address this one together with the next disadvantage.
• Not clear which command combinations are allowed (for example, can wait-for only be combined with start or also with import)
  • The only commands that I can think of that would have issues for automation purposes, would be the wait-for commands, but, to avoid potential confusion, we can suffix the two commands with the entities that they're waiting for. (eg: sast-scan wait-for-scan ::myScan or sast-scan wait-for-import ::myImport::. If those command names are too long, then maybe we rename them to wait-scan and wait-import ? If we're concerned about the commands being too long, then I feel that the command completion scripts address this problem. (Though currently not available for windows/powershell).

Finally (this is just my (very) humble opinion/hot-take), I think the 3-level command convention that we have (<product> <entity> <action>) is the most prominent design characteristic that every fcli-user will have memorized and at the forefront of their minds when using fcli. If we decide the create a 4th level (which I think is far too many), then we'll want to refactor the other on-prem products (ssc, sc-sast, sc-dast) to follow the same convention so that we maintain consistency. But again, I'd like to avoid that if possible as I think that will, to a great extent, hinder the user experience.