{"id":25506541,"url":"https://github.com/blackducksoftware/sage","last_synced_at":"2025-10-29T04:18:50.336Z","repository":{"id":34846728,"uuid":"173361636","full_name":"blackducksoftware/sage","owner":"blackducksoftware","description":"A tool for inspecting the usage of a Black Duck instance and offering wisdom about how to make better use of the system","archived":false,"fork":false,"pushed_at":"2023-03-29T13:51:02.000Z","size":217,"stargazers_count":8,"open_issues_count":3,"forks_count":8,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-24T10:45:38.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackducksoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-01T20:09:00.000Z","updated_at":"2023-04-20T16:06:03.000Z","dependencies_parsed_at":"2022-08-08T02:01:18.021Z","dependency_job_id":null,"html_url":"https://github.com/blackducksoftware/sage","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fsage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fsage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fsage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fsage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackducksoftware","download_url":"https://codeload.github.com/blackducksoftware/sage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248215192,"owners_count":21066622,"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":[],"created_at":"2025-02-19T06:58:21.185Z","updated_at":"2025-10-29T04:18:45.305Z","avatar_url":"https://github.com/blackducksoftware.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Sage\n\nAnalyze usage of a Black Duck system and offer sage advice for how to improve usage and get the most value out of the product. Identifies issues which represent poor practices and/or areas where best practices could/should be applied.\n\n## Table Of Contents\n\n- [Goals](#goals)\n- [How to Run and Get Results](#run)\n- [Release History](#release-history)\n\n## Goals \u003ca name=\"goals\"/\u003e\n\n* Detect bad scanning practices which will result in poor system performance and/or inaccurate analysis results\n* Easy to run\n* Easy to understand guidance\n* Easy to share results\n\n# How to Run and Get Results \u003ca name=\"run\" /\u003e\n\nSage uses:\n\n- Python3\n- Credentials or an API token from your Black Duck server\n  - The associated user account needs to have visibility to all the projects, versions, and scans you want to analyze, e.g. has role 'System Administrator', 'Super User', or 'Global Code Scanner'\n- Highly recommended: [virtualenv](https://virtualenv.pypa.io/en/latest/), [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)\n\nSage produces analysis output in json format so it's easy to read (using a tool like jq) and it's easy to use as input to the other tools which might want to act on the information.\n\nTo run,\n\n```bash\nmkvirtualenv sage # optional, but again, nice to use virtualenv and virtualenvwrapper\npip3 install -r requirements.txt\npython3 sage.py -h # for help\npython3 sage.py https://your-hub-dns {api-token}\npython3 sage.py https://your-hub-dns {api-token} -j # include jobs statistics\n```\n\n## Using a Proxy\n\nSage uses the blackduck PyPi library which, in turn, uses the Python requests library. The requests library supports use of proxies which can be configured via environment variables (see details at https://requests.readthedocs.io/en/master/user/advanced/), e.g.\n\n```\n$ export HTTP_PROXY=\"http://10.10.1.10:3128\"\n$ export HTTPS_PROXY=\"http://10.10.1.10:1080\"\n```\n\n## Output\n\nAnalysis output is written, by default, to `/var/log/sage_says.json`. Use the -f option to specify a different path/filename to write the output into.\n\nWhat you can expect to get,\n\n```json\njq 'keys' \u003c sage_says.json\n[\n  \"hub_url\",\n  \"hub_version\",\n  \"job_statistics\",\n  \"number_bom_scans\",\n  \"number_signature_scans\",\n  \"policies\",\n  \"projects\",\n  \"projects_with_too_many_versions\",\n  \"sage_version\",\n  \"scans\",\n  \"time_of_analysis\",\n  \"total_projects\",\n  \"total_scan_size\",\n  \"total_scans\",\n  \"total_unmapped_scans\",\n  \"total_versions\",\n  \"unmapped_scans\",\n  \"versions_with_too_many_scans\",\n  \"versions_with_zero_scans\"\n]\n```\n\n```\n jq '.projects_with_too_many_versions' \u003c sage_says.json # shows projects with \u003e X versions\n jq '.total_unmapped_scans' \u003c sage_says.json # show number of un-mapped scans\n jq '.unmapped_scans' \u003c sage_says.json # show the list of un-mapped scans\n jq '.projects[] | \"\\(.name), \\(.scanSize), \\(.num_versions)\"' sage_says.json | sed -e 's\u0026^\"\u0026\u0026' -e 's\u0026\"$\u0026\u0026' \u003e projects_and_sizes.csv # Generate a CSV list of projects with their scan sizes\n```\n\nOutput from Sage can form the input to other tools. For instance, the list of unmapped scans can be fed into another program that reads the scan (aka code location) URL and performs a DELETE on it to delete the un-mapped scan (aka code location).\n\nYou can also use https://viewer.dadroit.com tool for analysis of .JSON output.\n\n# Release History \u003ca name=release-history /\u003e\n\n## Version 2.3.1\n2021-04-28\n\n- Add projectOwner\n- Add project version activity to csv script\n- Add filter activity script\n\n## Version 2.3\n2021-04-27\n\n- Refactor to use new Client from hub-rest-api-python\n- Copy common attributes for scan summaries\n\n## Version 2.2\n2021-04-12\n\n- Robustness and performance improvements by utilizing the same requests.Session\n- retries, timeouts (default 3 retries, 15 sec timeout)\n- allow password in addition to access token authentication\n- bearer token auto-renewal to allow \u003e 2h running time\n- fetch entities through pagination instead of hard-coded limits\n- added elapsed time\n- output warning about incomplete scan-summaries with 2020.8 and 2020.10\n- identify projects without an owner\n\nBugs fixed:\n- crash with missing createdAt or updatedAt\n- crash with spans with \u003c 2 elements\n- analysis output messages no longer overwrite each other\n\n\n## Version 2.0\n2020-02-14\n\n- Refactored the code to make it simpler, easier to maintain and test\n- Added unit tests using pytest\n- Adding more metadata, e.g.\n  - total scans\n  - total scan size (for all signature scans)\n  - total projects\n  - total versions\n  - ...and more\n\n## March 6, 2019\n\nAdding more fine-grained analysis of projects\n\n## March 3, 2019\n\nAdded job information\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackducksoftware%2Fsage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackducksoftware%2Fsage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackducksoftware%2Fsage/lists"}