Improve fcli documentation

[rsenden]

Enhancement Request

There have been various requests for improving the fcli documentation, both around documentation structure/format, and adding additional content.

Regarding structure/format, following are some potential enhancements:

• The manual pages are difficult to navigate, as you need to drill down from the top-level fcli command to the command that you're actually looking for, and there's no single overview of all fcli commands that are available. Some ideas to improve this:
  • Provide an index page that lists all fcli commands, ideally together with usage header, linking to the respective manual pages.
  • Alternatively, have each manual page not only list direct sub-commands, but (also) list the full tree of sub-commands. Effectively, the top-level fcli manual page would then list all fcli commands, the fcli ssc manual page would list all SSC-related commands, ... This allows for even easier navigation than a separate index page, but may be more difficult to implement.
  • Provide a breadcrumb navigation header that shows parent commands, for example allowing users to quickly navigate from the fcli ssc appversion list manual page to the parent fcli ssc appversion or fcli ssc or fcli manual pages. If we have a separate index page listing all fcli commands, that should be the first link in the breadcrumb header.
  • Even better would be if the breadcrumb header provides drop-down menus to select other siblings. For example, the fcli ssc breadcrumb item would show a drop-down menu to navigate to fcli fod, fcli sc-sast, ...
  • Instead of, or in addition to the above, it may be useful to have a single-page document that contains all manual pages for all fcli commands, with a proper table of contents to navigate to the the documentation for individual commands.
  • Note that manual pages are automatically generated using picocli, so it may be difficult to customize the output, but we may be able to post-process the picocli-generated manual pages to provide better navigation.
• Provide a single PDF document that includes both the top-level documentation page and all manual pages.
  • Note that we already provide downloadable documentation for offline/air-gapped use, but a single PDF document may be easier ,especially if you want to search through the full documentation set.
• Given that the main documentation is quite long, especially if we also add content like the below, maybe we should better organize this and potentially split into multiple pages? Maybe we should have one document that describes general fcli usage and concepts, and another page that lists various use cases like sample pipeline scripts, ...?

Regarding content, some potential enhancements:

• Add manpage-style documentation for built-in actions; currently the only way to see available actions and usage instructions is by running fcli * action list and fcli * action help commands. Maybe we can have picocli generate these by dynamically adding built-in actions as proper picocli sub-commands for the action run and action help commands, or alternatively we may need to generate these manual pages ourselves and update picocli-generated action * manual pages to list built-in actions and link to corresponding man-pages.
• Examples on how to create policy check actions; potentially we could just include/link to the sample actions in the source code repo.
• Sample pipeline scripts, for example showing a sequence of commands like the following:
  • Download/install fcli (or use Docker image)
  • fcli tool sc-client install
  • scancentral package
  • fcli fod sast-scan start or fcli sc-sast scan start
  • fcli * wait-for
  • One or more fcli * action run commands to check policy, export data, ...
• Explicit documentation/sample commands for running the various built-in actions like SARIF export

[rsenden]

Also see remkop/picocli#2337