github.com/joey-fossa/fossa-cli@v0.7.34-0.20190708193710-569f1e8679f0/README.md (about) 1  2 3 <p align="center"> 4 <b>fossa-cli</b> - Fast, portable, and reliable dependency analysis for any codebase. 5 </p> 6 7 <p align="center"> 8 <a href="https://app.fossa.io/projects/git%2Bgithub.com%2Ffossas%2Ffossa-cli?ref=badge_shield" alt="FOSSA Status"> 9 <img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Ffossas%2Ffossa-cli.svg?type=shield"/> 10 </a> 11 <a href="https://circleci.com/gh/fossas/fossa-cli" alt="CircleCI Tests"> 12 <img src="https://circleci.com/gh/fossas/fossa-cli.svg?style=shield&circle-token=f55f707e21ac39a80127d3372a1a1452ec94f4f7"/> 13 </a> 14 <a href="https://goreportcard.com/report/github.com/fossas/fossa-cli"> 15 <img src="https://goreportcard.com/badge/github.com/fossas/fossa-cli"> 16 </a> 17 <a href="https://golangci.com/r/github.com/fossas/fossa-cli"> 18 <img src="https://golangci.com/badges/github.com/fossas/fossa-cli.svg"> 19 </a> 20 <a href="https://codecov.io/gh/fossas/fossa-cli"> 21 <img src="https://codecov.io/gh/fossas/fossa-cli/branch/master/graph/badge.svg" /> 22 </a> 23 </p> 24 25 ## Background 26 27 `fossa` analyzes complex codebases to generate dependency reports and license notices. It can generate fast and highly-accurate results, by leveraging existing build environments. Refer to the [FOSSA CLI User Manual](docs/README.md#fossa-cli-documentation) for in depth information about using this tool. 28 29 **Features:** 30 31 - Supports over 20+ languages & environments (JavaScript, Java, Ruby, Python, Golang, PHP, .NET, etc...) 32 - Auto-configures for monoliths; instantly handles multiple builds in large codebases. 33 - Fast & portable; a cross-platform binary you can drop into CI or dev machines. 34 - Generates offline documentation for license notices & third-party attributions. 35 - Tests dependencies against license violations, audits and vulnerabilities (coming soon!) by integrating with https://fossa.com. 36 37 ## Installation 38 39 The following commands will execute scripts to fetch and install the latest [GitHub Releases](https://github.com/fossas/fossa-cli/releases) on the corresponding operating system. 40 41 ### MacOS (Darwin) or Linux amd64: 42 ```bash 43 curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash 44 ``` 45 46 ### Windows with Powershell: 47 ```powershell 48 Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/fossas/fossa-cli/master/install.ps1')) 49 ``` 50 51 Add `C:\ProgramData\fossa-cli` to your path by modifying your `profile.ps1` file or temporarily with the following command: 52 ```powershell 53 $env:Path += ";C:\ProgramData\fossa-cli" 54 ``` 55 56 ## Quick Start 57 58 Run `fossa` and provide a [FOSSA API Key](https://docs.fossa.com/docs/api-reference) to create a local [configuration file](docs/config-file.md#fossayml) and analyze the project. The project information will be uploaded and a link to a rich, hosted report on [fossa.com](https://fossa.com) will be output: 59 60 ```bash 61 FOSSA_API_KEY="YOUR_API_KEY_HERE" fossa 62 63 # Output: 64 # ========================================================== 65 # 66 # View FOSSA Report: https://app.fossa.com/{YOUR_LINK} 67 # 68 # ========================================================== 69 ``` 70 > Note: Running [`fossa`](docs/user-guide.md/#fossa) is equivalent to running [`fossa init`](docs/user-guide.md#fossa-init) followed by [`fossa analyze`](docs/user-guide.md#fossa-analyze). 71 ## Documentation 72 73 If you run into a problem using the FOSSA CLI, most issues can be resolved by looking at our documentation in the [FOSSA CLI User Manual](docs/README.md#fossa-cli-documentation). This will shed light to how we analyze specific ecosystems and how to accurately configure your project. 74 75 If you have questions please refer to the [FAQ](docs/faq.md#frequently-asked-questions). If your question is related to a bug or feature please open an issue on GitHub. You can also reach out to fossa directly at support@fossa.com. 76 77 If you are interested in learning more about FOSSA you can visit our homepage at fossa.com and look at our [online documentation](https://docs.fossa.com/docs). 78 79 ## Supported Environments 80 | Environment | Package Managers | 81 | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | 82 | Android | [Gradle](docs/integrations/gradle.md#gradle) | 83 | [Debian](docs/integrations/debian.md#debian) | Dpkg | 84 | [Golang](docs/integrations/golang.md#go) | Dep, Gomodules, Vndr, GDM, Glide, Godep, Govendor | 85 | Groovy | [Gradle](docs/integrations/gradle.md#gradle) | 86 | [Haskell](docs/integrations/haskell.md#haskell) | Cabal and Stack | 87 | Java | [Gradle](docs/integrations/gradle.md#gradle), [Maven](docs/integrations/maven.md#maven), [Ant](docs/integrations/ant.md#ant--ivy) | 88 | Javascript | [nodejs & npm](docs/integrations/nodejs.md#nodejs) | 89 | Kotlin | [Gradle](docs/integrations/gradle.md#gradle) | 90 | Monorepo tooling | [okbuck](docs/integrations/okbuck.md#okbuck), [Buck](docs/integrations/buck.md#buck) | 91 | [.NET](docs/integrations/nuget.md#nuget-net) | NuGet, Paket | 92 | Objective-C | [Cocoapods](docs/integrations/cocoapods.md#cocoapods), [Carthage](docs/integrations/carthage.md#carthage) | 93 | PHP | [Composer](docs/integrations/composer.md#composer) | 94 | [Python](docs/integrations/python.md#python) | Pip, Pipenv, requirements.txt | 95 | [Ruby](docs/integrations/ruby.md#ruby) | Bundler | 96 | [Rust](docs/integrations/rust.md#rust) | Cargo | 97 | Scala | [SBT](docs/integrations/sbt.md#sbt) | 98 | Swift | [Cocoapods](docs/integrations/cocoapods.md#cocoapods), [Carthage](docs/integrations/carthage.md#carthage) | 99 | C, C++ | [Archive Uploader](docs/integrations/archive.md#archive) | 100 101 If your development environment is not supported, check out the [archive](docs/integrations/archive.md#archive) uploader which allows direct license scanning of source code files. 102 103 [Click here to learn more](docs/user-guide.md#user-guide) about the technical details behind this project. 104 105 ## Configuration 106 107 ```bash 108 fossa init # writes to `.fossa.yml` 109 ``` 110 111 Running `fossa init` will create a hidden configuration file called [`.fossa.yml`](docs/config-file.md#fossayml) which looks like this: 112 113 ```yaml 114 version: 1 115 cli: 116 server: https://app.fossa.com 117 fetcher: custom 118 project: github.com/fossas/fossa-cli 119 analyze: 120 modules: 121 - name: fossa-cli 122 type: go 123 target: github.com/fossas/fossa-cli/cmd/fossa 124 path: ./cmd/fossa 125 ``` 126 127 Check out the [User Guide](docs/user-guide.md#user-guide) to learn about editing this file. 128 129 After [configuration](docs/user-guide.md#1-configuring-a-project), you can now [analyze](docs/user-guide.md#2-analyzing-a-project) the project and upload new results: 130 131 ```bash 132 # Run FOSSA analysis and preview the results to be uploaded. 133 fossa analyze -o 134 135 # Run FOSSA and upload results 136 # Going forward, you only need to run this one-liner 137 FOSSA_API_KEY=YOUR_API_KEY_HERE fossa analyze 138 ``` 139 140 ## Integrating with CI 141 142 ### Testing for License Violations 143 If you've integrated with https://fossa.com, you can use [`fossa test`](docs/user-guide.md#fossa-test) to fail builds against your [FOSSA scan status](https://app.fossa.io/projects/git%2Bgithub.com%2Ffossas%2Ffossa-cli/refs/branch/master/5e225327846320e9dfb8bf12673afa2eb4144fb4/preview). 144 145 ```bash 146 # Exit with a failing status and dump an issue report to stderr 147 # if your project fails its license scan 148 FOSSA_API_KEY=YOUR_API_KEY_HERE fossa test 149 150 # Output: 151 # -------------------------- 152 # - exit status (1) 153 # 154 # * FOSSA discovered 7 license issue(s) in your dependencies: 155 # 156 # UNLICENSED_DEPENDENCY (3) 157 # * pod+FBSnapshotTestCase$1.8.1 158 # * pod+FBSnapshotTestCase$2.1.4 159 # * pod+Then$2.1.0 160 # 161 # POLICY_FLAG (4) 162 # * mvn+com.fasterxml.jackson.core:jackson-core$2.2.3 163 # * npm+xmldom$0.1.27 164 # * pod+UICKeyChainStore$1.0.5 165 # * gem+json$1.7.7 166 # 167 # ✖ FOSSA license scan failed: 7 issue(s) found. 168 ``` 169 170 ### Generating License Notices 171 172 You are able to generate a license notice with each CI build using the [`fossa report`](docs/user-guide.md#fossa-report) command: 173 174 ```bash 175 # write a license notice to NOTICE.txt 176 fossa report --type licenses > NOTICE.txt 177 ``` 178 179 [See this repo's NOTICE file](NOTICE) for an example. 180 181 License data is provided by [https://fossa.com](https://fossa.com)'s 500GB open source registry. 182 183 ## Development 184 185 View our [Contribution Guidelines](.github/CONTRIBUTING.md) to get started. 186 187 ## License 188 189 `fossa` is Open Source and licensed under the [MPL-2.0](https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)). 190 191 You are free to use `fossa` for commercial or personal purposes. Enjoy! 192 193 [](https://app.fossa.io/projects/git%2Bgithub.com%2Ffossas%2Ffossa-cli?ref=badge_large)