Ficus debug logs (#1610)

When you pass the `--debug` flag into `fossa analyze`, `fossa container analyze` or `fossa sbom analyze`, the debug bundle is not created in a file called `fossa.debug.zip`. This zip file contains `fossa.debug.json` and `fossa.telemetry.json`.

If you are doing snippet scanning, then it will also contain debug logs from Ficus.

Author: spatten

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,7 +21,7 @@ Steps to reproduce the behavior:
 A clear and concise description of what you expected to happen.
 
 **Debug bundle**
-Please run `fossa` with the `--debug` flag and attach the resulting `fossa.debug.json.gz` file here.
+Please run `fossa` with the `--debug` flag and attach the resulting `fossa.debug.zip` file here.
 
 **Additional context**
 Add any other context you think is relevant about the problem here.

.gitignore

@@ -25,6 +25,7 @@ sandbox/
 fossa.debug.json
 fossa.debug.json.gz
 fossa.telemetry.json
+fossa.debug.zip
 
 # Integration Tests
 integration-test/artifacts/
@@ -42,4 +43,4 @@ target/
 
 # Include targets in test
 !test/reachability/testdata/maven-default/target
-!test/reachability/testdata/maven-build-config/dist
+!test/reachability/testdata/maven-build-config/dist

Changelog.md

@@ -1,5 +1,8 @@
 # FOSSA CLI Changelog
 
+## 3.13.0
+- Change how debug logs are generated. They are now generated in a file called fossa.debug.zip, which can contain multiple files. For the common case of `fossa analyze --debug`, it will now contain the debug bundle (fossa.debug.json) and the telemetry json (fossa.telemetry.json). It will also contain Ficus logs if Ficus is run via --x-snippet-scan ([#1610](https://github.com/fossas/fossa-cli/pull/1610))
+
 ## 3.12.3
 - Licensing: applies a fix for proprietary license detection ([#1616](https://github.com/fossas/fossa-cli/pull/1616))
 

docs/contributing/telemetry.md

@@ -2,22 +2,22 @@
 
 ## Overview
 
-The telemetry lifecycle is implemented via `bracket`. We provision `TelemetryCtx` 
-during setup and during teardown and we perform sink Telemetry records. We do 
+The telemetry lifecycle is implemented via `bracket`. We provision `TelemetryCtx`
+during setup and during teardown and we perform sink Telemetry records. We do
 not use (producer-consumer threaded) pattern for emitting logs. This is to preserve
-simplicity and limit network requests to a minimum. The current telemetry requirements 
-allow us to ship a reasonably small payload (<200kb). 
+simplicity and limit network requests to a minimum. The current telemetry requirements
+allow us to ship a reasonably small payload (<200kb).
 
-Within TelemetryCtx, 
+Within TelemetryCtx,
 
 - We use `TBMQueue` for listed logs, results, and measures.
 - We use `STM` for atomic counters and data containers.
 - We use `TMVar` for setting a one-time sink or command information.
 
 ## Telemetry Scope and User Interface
 
-Telemetry scope is configurable by the user. Telemetry scope can be 
-configured via the following options in order of precedence: 
+Telemetry scope is configurable by the user. Telemetry scope can be
+configured via the following options in order of precedence:
 
 1. Command line option (`--with-telemetry-scope=off|full`)
 2. Environment variable (`FOSSA_TELEMETRY_SCOPE=off|full`)
@@ -32,18 +32,20 @@ telemetry:
 ```
 
 For instance, if both the command-line option and the environment variable are provided
-the telemetry scope provided via the command line will be used. 
-	
+the telemetry scope provided via the command line will be used.
+
 Supported telemetry scopes:
-- `off` - telemetry results are not captured or emitted. 
+- `off` - telemetry results are not captured or emitted.
 - `full` - telemetry results are uploaded to the default or specified endpoint.
-	
+
 When we do not have `ApiOpts` (e.g. API Key), we do not emit telemetry to an endpoint.
 
 ## Telemetry Sinks
 
-When the environment variable `FOSSA_TELEMETRY_DEBUG=1` or `--debug` flag is provided, 
-the telemetry sink is set to file. This will generate the file `fossa.telemetry.json` in the current working directory. 
+When the environment variable `FOSSA_TELEMETRY_DEBUG=1` or `--debug` flag is provided,
+the telemetry sink is set to file. The `--debug` flag will generate a file called `fossa.debug.zip` in the current working directory, which will contain a file called `fossa.telemetry.json`.
+
+The `FOSSA_TELEMETERY_DEBUG` variable is set to 1 and the `--debug` flag is not passed in, then we will write `fossa.telemetry.json` in the current working directory.
 
 Telemetry is sunk to the same server as the analysis.
 
@@ -65,15 +67,15 @@ experimental (SomeProject manifestDir manifestFile) = do
 
 2. Captured system and CLI version information
 
-This is automatically done at teardown. If we do not have version identifier, 
-we consider CLI environment to be development. CLI version is set as git tag, 
+This is automatically done at teardown. If we do not have version identifier,
+we consider CLI environment to be development. CLI version is set as git tag,
 or branch name. This information is exact as data collected in debug bundle.
 
 3. Capturing errors and warnings
 
 ## teleRunDiagnosticsIO
 
-```haskell 
+```haskell
 -- >> :t trackResult
 -- trackResult :: Has Telemetry sig m => Result a -> m ()
 
@@ -86,7 +88,7 @@ bar = do
 4. Capturing cpu time of a computation
 
 ```haskell
--- >> :t trackTimeSpent 
+-- >> :t trackTimeSpent
 -- trackTimeSpent :: Has Telemetry sig m => Text -> m a -> m a
 
 someComplexComputation :: Has Telemetry sig m => m ()
@@ -97,7 +99,7 @@ someComplexComputation = do
 
 5. Tracking raw telemetry messages
 
-Avoid using this interface as much as possible. It produces type-free telemetry data and 
+Avoid using this interface as much as possible. It produces type-free telemetry data and
 we want to capture telemetry data that has explicit/strict data shape.
 
 ```haskell
@@ -111,8 +113,8 @@ foo = do
 
 ### Future
 
-We can implement `span` and `trace`s to provide capability to continuous profiling, this 
-can be done by modifying `trackTimeSpent` to `trackSpan`. 
+We can implement `span` and `trace`s to provide capability to continuous profiling, this
+can be done by modifying `trackTimeSpent` to `trackSpan`.
 
 ```
 <---------------------------------> ~ Trace
@@ -122,5 +124,5 @@ can be done by modifying `trackTimeSpent` to `trackSpan`.
 ```
 
 Ideally, we can leverage existing sdk from apm provider, or open telemetry instead of
-building this capability in-house. 
+building this capability in-house.
 

docs/differences-from-v1.md

@@ -64,15 +64,15 @@ FOSSA 3.x supports following new build managers and languages:
 
 FOSSA CLI 3.x now does automatic analysis target discovery when you run `fossa analyze`. This means that `fossa init` is no longer required. `fossa init` is now a no-op that emits a warning, and will be removed in a future release.
 
-In 1.x, modules could be manually configured with "strategies" that specified _how_ a module should be analyzed. While `fossa init` attempted to choose the best strategy, manual intervention was sometimes required depending on the project's setup. 
+In 1.x, modules could be manually configured with "strategies" that specified _how_ a module should be analyzed. While `fossa init` attempted to choose the best strategy, manual intervention was sometimes required depending on the project's setup.
 
 In 3.x, the CLI now automatically selects the optimal strategy for analysis targets given the current environment (e.g. whether a build tool is available). This is possible because discovery and analysis are now one step, so we can check the suitability of analysis strategies while discovering targets.
 
 ### New fossa-deps configuration support
 
 With [`fossa-deps.{yml,json}` file](features/manual-dependencies.md), 3.x supports:
 
-- License scanning vendor dependencies 
+- License scanning vendor dependencies
 <!-- markdown-link-check-disable-next-line -->
 - Analyzing archives that are located at a specific web address (e.g. https://my-deps-source/v1.zip)
 - Manually specifying dependency by it's name and license (e.g. my-custom-dep with MIT license)
@@ -123,9 +123,9 @@ Following CLI commands are not supported with 3.x:
 ### Language Specific Changes
 
 #### Gradle
-- 3.x uses a new plugin-based strategy to perform discovery and analysis, it analyses all resolvable Gradle configurations. 
+- 3.x uses a new plugin-based strategy to perform discovery and analysis, it analyses all resolvable Gradle configurations.
 - 3.x does not accept any options: `cmd`, `task`, `timeout`, `all-configurations`, `configuration`, `retries`, `online`, `all-submodules`, and any other option supported in 1.x for Gradle analysis.
-- In 3.x, 
+- In 3.x,
    - There is no timeout (analysis may run for a long time)
    - All resolvable configurations are analyzed
    - There are no retries (CLI will attempt to analyze the project once)
@@ -134,7 +134,7 @@ Following CLI commands are not supported with 3.x:
 - Refer to [FOSSA 3.x gradle docs](references/strategies/languages/gradle/gradle.md) for more information for gradle.
 
 #### Clojure
-- 3.x performs the `lein deps :tree` strategy by default. 
+- 3.x performs the `lein deps :tree` strategy by default.
 - 3.x does not support any options - `strategy`, and `lien` for Clojure analysis.
 - Refer to [FOSSA 3.x clojure docs](references/strategies/languages/clojure/clojure.md) for more information on how 3.x performs analysis for clojure.
 
@@ -175,11 +175,11 @@ Following CLI commands are not supported with 3.x:
 #### Python
 - 3.x automatically selects the application strategy which yields the highest fidelity of dependency information.
 - 3.x uses attempts to infer requirements.txt for any file with prefix `req` in its name, and `txt` extension.
-- 3.x does not support the `strategy` or `requirement` option for Python analysis. 
+- 3.x does not support the `strategy` or `requirement` option for Python analysis.
 - Refer to [FOSSA 3.x python docs](references/strategies/languages/python/python.md) for more information on how 3.x performs analysis for python.
 
 #### Gem
-- 3.x attempts to use the `bundle show` command (`bundle` must be accessible from `$PATH`), and if it fails, it attempts to analyze dependencies from `Gemfile.lock` file. 
+- 3.x attempts to use the `bundle show` command (`bundle` must be accessible from `$PATH`), and if it fails, it attempts to analyze dependencies from `Gemfile.lock` file.
 - 3.x does not support `strategy` or `gemfile-lock-path` option for Gem Analysis.
 - Refer to [FOSSA 3.x gem docs](references/strategies/languages/ruby/ruby.md) for more information on how 3.x performs analysis for gem.
 
@@ -199,7 +199,7 @@ Since analysis targets are now automatically discovered during analysis, `fossa
 
 ### Migrate your .fossa.yml file
 
-We've made major breaking changes in the `.fossa.yml` file format for CLI 3.x to improve clarity. You'll need to migrate your 1.x `.fossa.yml` to the new 3.x format for their configurations to apply. `.fossa.yml` for 1.x will be ignored when running cli with version greater than 1.x. We determine whether a configuration file is compatible by examining its `version` field. 
+We've made major breaking changes in the `.fossa.yml` file format for CLI 3.x to improve clarity. You'll need to migrate your 1.x `.fossa.yml` to the new 3.x format for their configurations to apply. `.fossa.yml` for 1.x will be ignored when running cli with version greater than 1.x. We determine whether a configuration file is compatible by examining its `version` field.
 
 - .fossa.yml with version field value of `1` and `2` are for 1.x.
 - .fossa.yml with version field value of `3` are for 3.x, and 2.x.
@@ -234,7 +234,7 @@ For more information, including usage information, see [FOSSAv1 report compatibi
 
 FOSSA 1.x CLI is available and can be used indefinitely. We intend to make 3.x the default target for our installation scripts (as previously described in our documentation) in July 2022. If you wish to continue using 1.x, please migrate to using `install-v1` scripts.
 
-FOSSA will only patch 1.x for security fixes. Any feature and patch development work will occur in 3.x moving forth. 
+FOSSA will only patch 1.x for security fixes. Any feature and patch development work will occur in 3.x moving forth.
 
 #### I'm getting a poor result with latest version compared 1.x.
 
@@ -252,7 +252,7 @@ You can identify your cli version by performing `fossa --version` command.
 
 #### I'm running into an error - how do I debug?
 
-You can add `--debug` argument to your fossa commands (e.g. `fossa analyze --debug`), this will emit debug logs to stdout, and create `fossa.debug.json` in working directory. 
+You can add a `--debug` argument to your fossa commands (e.g. `fossa analyze --debug`), this will emit debug logs to stdout, and create a file called `fossa.debug.zip` in the working directory that contains a debug bundle (fossa.debug.json).
 
 #### What's the difference between FOSSA CLI 1.x, 2.x, and 3.x?
 
@@ -268,7 +268,7 @@ You can add `--debug` argument to your fossa commands (e.g. `fossa analyze --deb
 
 3.x will be released on November 12, 2021.
 
-> Note: There are no breaking changes from 2.x to 3.x. The 3.x version in functional sense, continuation of 2.x version. The 3.x version was released to (1) match the `version` field of the fossa configuration file with the major release version of cli, (2) mark migration of CLI 2.x source code back into the fossa-cli repository, and (3) mark 3.x now the default target for installation for all fossa users moving forwards. 
+> Note: There are no breaking changes from 2.x to 3.x. The 3.x version in functional sense, continuation of 2.x version. The 3.x version was released to (1) match the `version` field of the fossa configuration file with the major release version of cli, (2) mark migration of CLI 2.x source code back into the fossa-cli repository, and (3) mark 3.x now the default target for installation for all fossa users moving forwards.
 
 
 If you were previously using the installation script provided at [fossas/spectrometer](https://github.com/fossas/spectrometer/), it is now recommended to use the installation latest script provided at [fossas/fossa-cli](https://github.com/fossas/fossa-cli/).

docs/features/vuln_reachability.md

@@ -72,7 +72,7 @@ With this configuration, when FOSSA CLI analyzes a Maven or Gradle project at th
 ```bash
 fossa analyze --debug
 
-cat fossa.debug.json | jq '.bundleReachabilityRaw'
+unzip -p fossa.debug.zip fossa.debug.json | jq '.bundleReachabilityRaw'
 [
   {
     "callGraphAnalysis": {
@@ -113,7 +113,7 @@ cat fossa.debug.json | jq '.bundleReachabilityRaw'
 ]
 
 
-cat fossa.debug.json | jq '.bundleReachabilityEndpoint'
+unzip -p fossa.debug.zip fossa.debug.json | jq '.bundleReachabilityEndpoint'
 {
  # content uploaded to endpoint
 }
@@ -129,7 +129,8 @@ the your target jar. If you are running into issues with reachability, please co
 
 ```bash
 # get what we sent to endpoint
-cat fossa.debug.json | jq '.bundleReachabilityEndpoint' > rawReachabilityJob.json
+
+unzip -p fossa.debug.zip fossa.debug.json | jq '.bundleReachabilityEndpoint' > rawReachabilityJob.json
 
 # run job in dry mode
 >> yarn repl
@@ -183,7 +184,7 @@ You can inspect the data by running:
 
 ```bash
 ; fossa analyze --output --debug # --output to not communicate with endpoint
-; gunzip fossa.debug.json.gz     # extract produced debug bundle
+; unzip fossa.debug.zip fossa.debug.json # extract produced debug bundle
 
 # content in .bundleReachabilityRaw is uploaded
 # to endpoint for reachability analysis.

docs/references/debugging/README.md

@@ -6,8 +6,8 @@ This reference describes how to debug it and in what situations you may want to.
 The intended audience for this reference is both FOSSA employees and any users
 who want to debug FOSSA CLI themselves.
 
-If you are a reader inside or outside the FOSSA organization and see anything 
-that could be improved in this document, please open a pull request or 
+If you are a reader inside or outside the FOSSA organization and see anything
+that could be improved in this document, please open a pull request or
 drop us a note on [support.fossa.com](https://support.fossa.com)!
 
 ## Using this reference
@@ -93,21 +93,29 @@ fossa analyze --debug
 
 After this has run, a new file is created in the current
 working directory (the directory from which you launched `fossa`).
-This file is titled `fossa.debug.json.gz`.
+This file is titled `fossa.debug.zip`. Its contents can vary depending on the exact command you are running.
+But it will almost always contain the debug bundle in fossa.debug.json.
 
 ### Extracting a debug bundle
 
-The FOSSA CLI debug bundle is a gzipped JSON file,
-so can be extracted with just `gzip`:
+The FOSSA CLI debug bundle is a JSON file inside of fossa.debug.zip,
+
+If you want to extract every file in the zip:
+
+```
+; unzip fossa.debug.zip
+```
+
+
+If you only want the debug bundle, you can use
 ```
-; gunzip fossa.debug.json.gz
+; unzip fossa.debug.zip fossa.debug.json
 ```
 
-If you also want the JSON to be formatted,
-you can do this in a single line
+If you also want the JSON to be formatted, you can do this in a single line
 (if you have `jq` installed):
 ```
-; gunzip fossa.debug.json.gz --to-stdout | jq > fossa.debug.json
+; unzip -p fossa.debug.zip fossa.debug.json | jq > fossa.debug.json
 ```
 
 ### Reading a debug bundle

integration-test/Analysis/FicusSpec.hs

@@ -51,7 +51,7 @@ spec = do
       testDataExists <- PIO.doesDirExist testDataDir
       testDataExists `shouldBe` True
 
-      result <- runStack . runDiagnostics . ignoreStickyLogger . ignoreLogger . runExecIO . runReadFSIO $ analyzeWithFicus testDataDir apiOpts revision Nothing (Just 10)
+      result <- runStack . runDiagnostics . ignoreStickyLogger . ignoreLogger . runExecIO . runReadFSIO $ analyzeWithFicus testDataDir apiOpts revision Nothing (Just 10) Nothing
 
       case result of
         Success _warnings analysisResult -> do

integration-test/Container/AnalysisSpec.hs

@@ -14,7 +14,6 @@ import Container.Types (
  )
 import Data.Flag (toFlag')
 import Diag.Result (Result (..))
-import Effect.Logger (Severity (SevInfo))
 import Test.Hspec (Spec, aroundAll, describe, it, shouldBe, shouldSatisfy)
 
 spec :: Spec
@@ -30,10 +29,10 @@ registrySourceCfg =
     , usesExperimentalScanner = True
     , dockerHost = ""
     , arch = "amd64"
-    , severity = SevInfo
     , onlySystemDeps = False
     , filterSet = mempty
     , withoutDefaultFilters = toFlag' False
+    , debugDir = Nothing
     }
 
 runAnalyze :: ContainerAnalyzeConfig -> (ContainerScan -> IO ()) -> IO ()

spectrometer.cabal

@@ -243,6 +243,7 @@ library
     App.Fossa.Container.Sources.Podman
     App.Fossa.Container.Sources.Registry
     App.Fossa.Container.Test
+    App.Fossa.DebugDir
     App.Fossa.DependencyMetadata
     App.Fossa.DumpBinaries
     App.Fossa.EmbeddedBinary