{"id":22599586,"url":"https://github.com/singularityhub/stools","last_synced_at":"2025-06-30T03:02:41.107Z","repository":{"id":32000601,"uuid":"131198336","full_name":"singularityhub/stools","owner":"singularityhub","description":"singularity container tools for continuous integration and quality assessment","archived":false,"fork":false,"pushed_at":"2023-07-20T15:09:01.000Z","size":178,"stargazers_count":10,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-11T13:08:21.288Z","etag":null,"topics":["ci","clair","containers","continuous-integration","qa","scanning","singularity","singularity-containers"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/singularityhub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-26T18:56:19.000Z","updated_at":"2025-02-06T07:01:56.000Z","dependencies_parsed_at":"2025-04-11T01:33:31.907Z","dependency_job_id":"586e47eb-bf69-47a3-922f-cfdae866b1c4","html_url":"https://github.com/singularityhub/stools","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/singularityhub/stools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fstools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fstools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fstools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fstools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/singularityhub","download_url":"https://codeload.github.com/singularityhub/stools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fstools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260221329,"owners_count":22976859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","clair","containers","continuous-integration","qa","scanning","singularity","singularity-containers"],"created_at":"2024-12-08T11:10:26.856Z","updated_at":"2025-06-30T03:02:41.052Z","avatar_url":"https://github.com/singularityhub.png","language":"Python","readme":"# Singularity Container Tools\n\n[![PyPI version](https://badge.fury.io/py/stools.svg)](https://badge.fury.io/py/stools)\n\nThese are tools for Singularity containers, optimized for using with continuous integration for security\nand quality checks. For an example of the package being used in a continuous integration context, see the [stools-clair](https://github.com/singularityhub/stools-clair) repository.\n\n[![asciicast](https://asciinema.org/a/178712.png)](https://asciinema.org/a/178712)\n\nIn this work we will use [Clair OS](https://github.com/coreos/clair) combined with Continuous Integration\n(travis and circle) to scan [Singularity](https://singularityware.github.io) containers for security\nvulnerabilities. \n\n## Tags\n\nNote that after the first two releases, version numbers correspond with releases on pypi,\nand not Singularity versions.\n\n - [v0.0.13 (master)](https://github.com/singularityhub/stools) adds support for reports saving\n - [v3.2.1](https://github.com/singularityhub/stools/tree/v3.2.1) Uses Singularity v3.2.1 and above\n - [v2.4.5](https://github.com/singularityhub/stools/tree/v2.4.5) Uses Singularity v2.4.5\n\n## Background\nClair is intended to run as a server to continuous scan Docker *layers* for vulnerabilities. This doesn't map\nwell to the research domain because of the following:\n\n - Docker containers come in layers (.tar.gz files) while Singularity images are single binary files that don't \"plug in\" nicely to Clair.\n - Most researchers can't support continuous running of such a service.\n\nOn the other hand, a typical researcher *does* use services like [TravisCI](https://travis-ci.org) and [CircleCI](https://circle-ci.org) to\nrun their code bases against tests. Since these services now offer running containers and other service-type things, we in fact could do the following:\n\n - Spin up a Clair server during testing\n - Build a Singularity image, and scan the filesystem contents (before finalized in the image).\n\nWhile this isn't a continually running service, we can minimally ensure that a container is scanned each time\nit is built (and then likely merged to be used in production). If the user takes advantage of [Singularity Hub](https://www.singularity-hub.org) or [Singularity Registry Server](https://singularityhub.github.io/sregistry) the image will be pushed or built for production after passing \nthese various tests.\n\nThis experiment is based on early discussion in [this thread](https://github.com/singularityhub/sregistry/issues/14).\n\n\n## Basic Usage\n\nYou'll need to first clone the repository:\n\n```bash\ngit clone https://github.com/singularityhub/stools\ncd stools\n```\n\n### Build Containers\n\nIf you want, build the container (or use a tagged release from [Docker Hub](https://hub.docker.com/repository/registry-1.docker.io/vanessa/stools-clair/tags?page=1)).\n\n```bash\n$ docker build -t vanessa/stools-clair .\n```\n\nStart the application with [docker compose](https://docs.docker.com/compose/install/). \nNote that you should have the images you want to scan in the $PWD, which will be mapped to the container in `/code` \n(see the [docker-compose.yml](docker-compose.yml) file). You can change this around, just be sure that the containers you want to add are here.\n\n```bash\n$ docker-compose up -d\n```\n\nMake sure that your containers are up and running! There is one for the clair server\nthat we will interact with, and one for the database.\n\n```bash\n$ docker-compose ps\n    Name                   Command               State                            Ports                          \n-----------------------------------------------------------------------------------------------------------------\nclair-db        docker-entrypoint.sh postgres    Up      0.0.0.0:5432-\u003e5432/tcp                                  \nclair-scanner   /clair -config=/config/con ...   Up      0.0.0.0:6060-\u003e6060/tcp, 6061/tcp, 0.0.0.0:8080-\u003e8080/tcp\n```\n\nAlso note that the folder [reports](reports) by way of being in the mounted present working\ndirectory, will appear at `/code/reports` in the container. We will need to know this later.\n\n### Scan an Image\n\nLet's scan a local image in $PWD mapped to /code in the container. First\npull one from your registry of choice:\n\n```bash\n$ singularity pull shub://vsoch/singularity-images\n```\n\nAnd now let's scan! We do this by executing a command to the `clair-scanner` container.\nThe most basic usage will just print a report to stdout, like this:\n\n```bash\n$ docker exec -it clair-scanner sclair singularity-images_latest.sif\n...\n\nCVE-2016-9843 (Low)\nhttp://people.ubuntu.com/~ubuntu-security/cve/CVE-2016-9843\nThe crc32_big function in crc32.c in zlib 1.2.8 might allow context-dependent attackers to have unspecified impact via vectors involving big-endian CRC calculation.\n```\n\n### Save a Report\n\nHowever, if you want to save a report to file (json), you can add the `--report` argument\npointing to an existing output directory of choice. For example, since [reports](reports)\nis provided in our present working directory and already bound to the container at `/code/reports`\nwe can specify that as an argument:\n\n```bash\n$ docker exec -it clair-scanner sclair --report /code/reports singularity-images_latest.sif\n```\n\nUsing `--report` will not disable the print to stdout. However, if you want to disable it,\nyou can add the `--no-print` option. An example JSON report can be found in the [reports](reports) folder.\n\n```bash\n$ docker exec -it clair-scanner sclair --report /code/reports --no-print singularity-images_latest.sif\n```\n\nFor a full example of what is printed to stdout (using a container with a known vulnerability) see\nthe [example test](test) folder.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fstools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsingularityhub%2Fstools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fstools/lists"}