diff --git a/README.md b/README.md index a696fc3f..4061275e 100644 --- a/README.md +++ b/README.md @@ -12,70 +12,47 @@ [![codecov](https://codecov.io/gh/Samsung/LPVS/graph/badge.svg?token=XTD749ITNF)](https://codecov.io/gh/Samsung/LPVS) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7127519.svg)](https://doi.org/10.5281/zenodo.7127519) +--- ## Introduction -[Open-source code](https://en.wikipedia.org/wiki/Open-source_software) (that is a software that is freely available for use, study, modification, and distribution) must meet conditions of the respective license(s) of all of its dependencies. Miscompliance may lead to legal disputes, fines, obligation to disclose intellectual property, as well as reputational damage. - -In projects with numerous external dependencies, it becomes challenging to track license obligations accurately. Also, when many collaborators are involved, the risk of unintentional license violations, such as through copy-pasting code snippets, increases. Furthermore, there are nuanced situations like dependencies with dual licensing or licenses that may change due to ownership, purpose, or legislative alterations. These factors can potentially turn previously safe dependencies into unsafe ones over time. - -To address these license-related risks for open-source code, we have developed the _License Pre-Validation Service (LPVS)_. This tool provides a solution to mitigate potential license issues. By analyzing the project, _LPVS_ identifies its components and their respective licenses at every commit. Then it generates a list of potential issue cases, and communicates them to the developers as comments on GitHub. _LPVS_ offers a comprehensive description of possible license violations, including the details on the location of risky code and an overview of the specific license-related issues. - -With _LPVS_, we aim at assisting developers and project teams with ensuring license compliance for their open-source code. By providing insights into the potential license violations and their implications, _LPVS_ enables proactive management of license-related risks throughout the development process. - -We believe that _LPVS_ will be an invaluable tool for maintaining the integrity of open-source projects and safeguarding against license infringements. - -## Features - -- License Scanners: - - _LPVS_ integrates with the [SCANOSS](https://www.scanoss.com) license scanner, allowing for comprehensive license analysis of the project's components. SCANOSS helps to identify the licenses associated with the codebase, ensuring the compliance with open-source license requirements. By leveraging SCANOSS, _LPVS_ provides accurate and up-to-date information on the licenses used in the project. - -- GitHub Review System Integration: - _LPVS_ seamlessly integrates with the GitHub review system, enhancing the collaboration and code review process. _LPVS_ automatically generates comments on GitHub, highlighting potential license violations or issues within the codebase. This integration streamlines the review process, making it easier for the developers and collaborators to identify and address license-related concerns directly within the GitHub environment. - -- Comprehensive Issue Description: - - _LPVS_ provides a detailed and comprehensive description of possible license violations within the project. This includes specific information on the location of potentially risky code and an overview of the license-related issues at hand. By offering this comprehensive insight, _LPVS_ enables the developers to have a clear understanding of license-related risks within their codebase and to take appropriate steps to mitigate them. - -- Continuous Monitoring: - - _LPVS_ facilitates continuous monitoring of license-related risks throughout the development process. By analyzing each commit, _LPVS_ ensures that any changes or additions to the codebase are assessed for potential license violations. This ongoing monitoring allows developers to proactively manage license compliance and address any issues that arise in a timely manner. - -- Risk Mitigation: +The **License Pre-Validation Service (LPVS)** is a tool designed to address license-related risks in the source code. +It helps developers ensure license compliance by analyzing project components and flagging potential issues at each update. +Use LPVS to protect your projects from license infringement. +--- - _LPVS_ aims at mitigating license-related risks by providing early detection and identification of potential violations. By alerting developers about potential issues and by providing the necessary information to understand and address them, _LPVS_ empowers teams to take proactive steps to ensure compliance with open-source licenses. This helps mitigate the risk of legal disputes, financial liabilities, and reputational damage associated with license violations. +## Features ✨ -With these features, _LPVS_ assists developers to manage license compliance for their open-source projects effectively. By integration with license scanning tools, supporting the GitHub review system, and providing comprehensive issue descriptions, _LPVS_ offers a robust solution for identifying and addressing license-related risks in the software development lifecycle. +- **License Checking**: Ensures open-source license compliance by analyzing project components. +- **Always Watching**: Continuously monitors license-related risks throughout the development process. +- **GitHub Integration**: Automatically generates comments on GitHub, highlighting potential license violations or issues within the codebase. --- -## Quick Start Guide & Build +## Usage 🚀 -- [_LPVS_ quick start guide](doc/docs/user-guide/service/quick-start-guide.md#quick-start-guide-1) -- [How to Build and Run _LPVS_ from Source Code](doc/quick-start-guide-and-build.md#how-to-build-and-run-lpvs-from-source-code-1) +Refer to the [Quick Start Guide], and then try running the tool. --- -## Frontend Source Code (React) +## Documentation 📚 -The frontend of the _LPVS_ project is implemented using React. The corresponding code can be found in the `frontend` folder. For detailed information about the frontend, please refer to the [Frontend README](frontend/README.md). - -To ensure compatibility between the LPVS frontend and backend, it's important to build the backend with the _"web"_ profile. +Full documentation is available at [GitHub pages]. --- -## License +## License 📝 -The _LPVS_ source code is distributed under the [MIT](https://opensource.org/licenses/MIT) open source license. +The LPVS source code is distributed under the [MIT] open source license. --- -## Contributing - -You are welcome to contribute to the _LPVS_ project. Contributing is a great way to practice social coding on GitHub, learn new technologies, and enhance your public portfolio. If you would like to contribute, please follow the guidelines below: +## Contributing 🤝 -- [How to Contribute Code](doc/docs/dev-guide/contributing.md) -- [How to Report a Security Vulnerability](.github/SECURITY.md) -- [Code Review Requirements](doc/docs/dev-guide/code-review-requirements.md) +You are welcome to contribute to the LPVS project. +Contributing is a great way to practice social coding on GitHub, learn new technologies, and enhance your public portfolio. +Please refer to the [Contributing guide] for more information on how to contribute. -Thank you for your interest in contributing to _LPVS_! Your contributions are highly appreciated. +[GitHub pages]: https://samsung.github.io/LPVS/ +[Contributing guide]: https://samsung.github.io/LPVS/dev-guide/contributing/ +[MIT]: https://opensource.org/licenses/MIT +[Quick Start Guide]: https://samsung.github.io/LPVS/quick-start-guide/ \ No newline at end of file diff --git a/doc/docs/dev-guide/README.md b/doc/docs/dev-guide/README.md index 69ace2da..f143fa86 100644 --- a/doc/docs/dev-guide/README.md +++ b/doc/docs/dev-guide/README.md @@ -15,7 +15,7 @@ in the navigation bar at the top of the page to move through the documentation i - [Integration guide] [Contributing guide]: contributing.md -[Testing policy]: testing_policy.md +[Testing policy]: testing-policy.md [Code review requirements]: code-review-requirements.md [API reference]: api.md -[Integration guide]: integration.md \ No newline at end of file +[Integration guide]: integration.md diff --git a/doc/docs/dev-guide/integration.md b/doc/docs/dev-guide/integration.md index 4a4448f4..d05db295 100644 --- a/doc/docs/dev-guide/integration.md +++ b/doc/docs/dev-guide/integration.md @@ -14,10 +14,12 @@ You can authenticate to GitHub Packages with Apache Maven by editing your Create a token with minimally sufficient rights: - Fine-grained tokens **(recommended)** + Only select repositories -> Permissions -> Repository permissions -> Metadata -> Read-only - Tokens (classic) - Select scopes -> read:packages_ + + Select scopes -> read:packages Create a new `~/.m2/settings.xml` file if one doesn't exist. diff --git a/doc/docs/dev-guide/testing_policy.md b/doc/docs/dev-guide/testing-policy.md similarity index 100% rename from doc/docs/dev-guide/testing_policy.md rename to doc/docs/dev-guide/testing-policy.md diff --git a/doc/docs/quick-start-guide.md b/doc/docs/quick-start-guide.md new file mode 100644 index 00000000..036e852a --- /dev/null +++ b/doc/docs/quick-start-guide.md @@ -0,0 +1,64 @@ +# Quick Start Guide + +Minimal configuration to set up and run the LPVS service locally. + +--- + +## Configure the repository + +To enable LPVS license scanning for your repository, you need to set up GitHub Webhooks: + +* Create a personal GitHub access token (`personal-token`) according to the [GitHub webhook configuration guide](user-guide/service/webhook.md#create-a-personal-github-access-token). + +* Get a personal Ngrok authentication token (`auth-token`) to expose your local service on the [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). + +* Configure the [webhook](user-guide/service/webhook.md#configure-the-webhook-in-your-github-repository-settings) in your GitHub repository settings. + +--- + +## Configure and run Docker images + +This section explains how to download and run pre-built LPVS Docker image with ngrok reverse proxy. + +### Set up LPVS Docker environment variables + +* Open `docker-compose-quick.yml` file. + +* In the `environment` part of `lpvs` section find and fill `github.login` and `github.token` (refer to the [guide](user-guide/service/docker.md#setting-up-lpvs-docker-environment-variables)). + +```yaml +- github.login= +- github.token= +``` + +* In the `environment` part of the `ngrok` section find and fill `auth-token` from [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). + +```yaml +- NGROK_AUTHTOKEN= +``` + +### Run LPVS and MySQL Docker images with `docker compose` + +* Start the LPVS services: + +```bash +docker compose -f docker-compose-quick.yml up -d +``` + +* To stop the LPVS services: + +```bash +docker compose -f docker-compose-quick.yml down +``` + +Configuration is now completed! + +## Test your pull request + +You can now create a new pull request or update an existing one with new commits. + +LPVS will automatically start the scan and provide a comment about the licenses found in the project. + +Example of the LPVS comment on GitHub: + +![result](img/result.png){: style="height:350px"} \ No newline at end of file diff --git a/doc/docs/user-guide/service/quick-start-guide.md b/doc/docs/user-guide/service/quick-start-guide.md deleted file mode 100644 index 47427746..00000000 --- a/doc/docs/user-guide/service/quick-start-guide.md +++ /dev/null @@ -1,69 +0,0 @@ -# Quick Start Guide - -Minimal configuration to set up and run the LPVS GitHub service locally. - ---- - -## Setting up your project to interact with _LPVS_ service - -To enable _LPVS_ license scanning for your project, you need to set up GitHub Webhooks. - -* Create a personal Github access token (`personal-token`): - - - Follow the instructions [here](/doc/docs/user-guide/service/webhook.md#create-a-personal-github-access-token) to create a personal access token with the necessary permissions. - -!!! warning - - Pay attention that the token must be copied immediately after creation, because you will not be able to see it later!! - -* Get a personal ngrok auth token to expose your local service (`auth-token`): - - - The ngrok agent authenticates with an authtoken. Your authtoken is available on the ngrok [portal](https://dashboard.ngrok.com/get-started/your-authtoken). - ---- - -## Using pre-built _LPVS_ Docker images - -This section explains how to download and run pre-built _LPVS_ Docker image with ngrok reverse proxy. - -For the Docker deployment scenario, you may need to set additional parameters described in [docker section](/doc/docs/user-guide/service/docker.md). - -### Setting up _LPVS_ Docker environment variables - -* Open `docker-compose-quick.yml` file. - -* In the `environment` part of the `lpvs` service, find `## Github data for fetching code` and fill in the github `login` and personal `token` that was generated earlier - -```yaml -- github.login= -- github.token= -``` - -* In the `environment` part of the `ngrok` service, find `## Ngrok Auth token` and fill personal `token` from [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). - -```yaml -- NGROK_AUTHTOKEN= -``` - -### Running _LPVS_ and MySQL Docker images with Docker Compose - -* Start the _LPVS_ services: - -```bash -docker compose -f docker-compose-quick.yml up -d -``` - -* To stop the _LPVS_ services, use next command: - -```bash -docker compose -f docker-compose-quick.yml down -``` - -## Setting up your project to interact with _LPVS_ - -Configure the [webhook](/doc/docs/user-guide/service/webhook.md#configure-the-webhook-in-your-github-repository-settings) in your GitHub repository settings - -Configuration from your project side is now complete! -You can now create a new pull request or update an existing one with commits. _LPVS_ will automatically start scanning and provide comments about the licenses found in the project. - -![result](../../img/webhook/result.png) \ No newline at end of file diff --git a/doc/docs/user-guide/service/webhook.md b/doc/docs/user-guide/service/webhook.md index b71e0fcc..a17275e9 100644 --- a/doc/docs/user-guide/service/webhook.md +++ b/doc/docs/user-guide/service/webhook.md @@ -11,7 +11,7 @@ To enable LPVS license scanning for your project, you need to set up GitHub Webh Follow the instructions [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token) to create a personal access token (`personal-token`) with the necessary permissions. -!!! note +!!! warning Pay attention that the token must be copied immediately after creation, because you will not be able to see it later! @@ -22,11 +22,11 @@ to create a personal access token (`personal-token`) with the necessary permissi To configure GitHub access to a personal server, you need to expose the URL to an external API. If the server has a dedicated IP address or domain, this step can be omitted. -- Install ngrok and connect your account from [Ngrok guide](https://ngrok.com/docs/getting-started/#step-2-install-the-ngrok-agent) (follow steps 1 and 2). +- Install Ngrok and connect your account from [Ngrok guide](https://ngrok.com/docs/getting-started/#step-2-install-the-ngrok-agent) (follow steps 1 and 2). -- If ngrok included in docker compose, auth token can be found on [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). +- If Ngrok is included in the docker compose file, `auth-token` can be found on [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). -- Run ngrok using the command: +- Run Ngrok using the command: ```bash ngrok http 7896 @@ -48,8 +48,9 @@ Follow the next steps: !!! note - If you're using ngrok, the `Payload URL` can be found on localhost: `http://127.0.0.1:4040/`. - It should be like `https://50be-62-205-136-206.ngrok-free.app/`. + If you're using Ngrok, the `Payload URL` can be found on localhost: `http://127.0.0.1:4040/`. + + It will look like `https://50be-62-205-136-206.ngrok-free.app/`. - Specify the content type as `application/json`. - Fill in the `Secret` field with the passphrase: `LPVS`. diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index b988c785..b7dd91bc 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -14,6 +14,7 @@ theme: markdown_extensions: - admonition + - attr_list - pymdownx.details - pymdownx.superfences - pymdownx.tasklist: @@ -28,7 +29,7 @@ plugins: nav: - Home: index.md - - Quick Start Guide: user-guide/service/quick-start-guide.md + - Quick Start Guide: quick-start-guide.md - User Guide: - User guide: user-guide/README.md - Service mode: @@ -48,7 +49,7 @@ nav: - Developer Guide: - Developer guide: dev-guide/README.md - Contributing guide: dev-guide/contributing.md - - Testing policy: dev-guide/testing_policy.md + - Testing policy: dev-guide/testing-policy.md - Code review requirements: dev-guide/code-review-requirements.md - API reference: dev-guide/api.md - Integration guide: dev-guide/integration.md