{"id":13717150,"url":"https://github.com/ossf/package-analysis","last_synced_at":"2026-02-27T06:59:07.853Z","repository":{"id":37787111,"uuid":"338377509","full_name":"ossf/package-analysis","owner":"ossf","description":"Open Source Package Analysis","archived":false,"fork":false,"pushed_at":"2025-04-01T22:51:45.000Z","size":3502,"stargazers_count":828,"open_issues_count":74,"forks_count":58,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-04-12T02:55:58.927Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/ossf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-02-12T16:50:54.000Z","updated_at":"2025-04-11T17:44:16.000Z","dependencies_parsed_at":"2023-10-16T15:13:36.630Z","dependency_job_id":"dc4baf4b-e9b8-4234-b6bb-4fb9dbd26768","html_url":"https://github.com/ossf/package-analysis","commit_stats":{"total_commits":760,"total_committers":23,"mean_commits":33.04347826086956,"dds":0.6710526315789473,"last_synced_commit":"ce4764ff758035c6209b8a3f4342b95350d547db"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fpackage-analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fpackage-analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fpackage-analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fpackage-analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ossf","download_url":"https://codeload.github.com/ossf/package-analysis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169329,"owners_count":22026211,"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":"2024-08-03T00:01:18.470Z","updated_at":"2026-02-27T06:59:07.815Z","avatar_url":"https://github.com/ossf.png","language":"Go","funding_links":[],"categories":["Dependency intelligence"],"sub_categories":[],"readme":"[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ossf/package-analysis/badge)](https://api.securityscorecards.dev/projects/github.com/ossf/package-analysis)\n\n# Package Analysis\n\nThe Package Analysis project analyses the capabilities of packages available on open source repositories. The project looks for behaviors that indicate malicious software: \n\n- What files do they access? \n- What addresses do they connect to? \n- What commands do they run? \n\nThe project also tracks changes in how packages behave over time, to identify when previously safe software begins acting suspiciously. \n\nThis effort is meant to improve the security of open source software by detecting malicious behavior, informing consumers selecting packages, and providing researchers with data about the ecosystem. \n\nThis code is designed to work with the\n[Package Feeds](https://github.com/ossf/package-feeds) project,\nand originally started there.\n\nFor examples of what this project has detected, check out the\n[case studies](docs/case_studies.md).\n\n## How it works\n\nThe project's components are:\n\n- A [scheduler](./cmd/scheduler/) - creates jobs for the analysis worker from\n  Package Feeds.\n- Analysis (one-shot [analyze](./cmd/analyze/) and [worker](./cmd/worker/)) -\n  collects package behavior data through static and dynamic analysis of each\n  package.\n- A [loader](./function/loader/) - pushes the analysis results into BigQuery.\n\nThe goal is for all of these components to work together and provide extensible,\ncommunity-run infrastructure to study behavior of open source packages and to\nlook for malicious software. We also hope that the components can be used\nindependently, to provide package feeds or runtime behavior data for anyone\ninterested.\n\nThe Package Analysis project currently consists of the following pipeline:\n\n![image](docs/images/Pipeline%20diagram.png)\n\n1. Package repositories are monitored for new packages.\n1. Each new package is scheduled to be analyzed by a pool of workers.\n1. A worker performs dynamic analysis of the package inside a sandbox.\n1. Results are stored and imported into BigQuery for inspection.\n\nSandboxing via [gVisor](https://gvisor.dev/) containers ensures the packages are\nisolated. Detonating a package inside the sandbox allows us to capture strace\nand packet data that can indicate malicious interactions with the system as well\nas network connections that can be used to leak sensitive data or allow remote\naccess.\n\n## Public Data\nThis data is available in the public [BigQuery dataset](https://console.cloud.google.com/bigquery?d=packages\u0026p=ossf-malware-analysis\u0026t=analysis\u0026page=table).\n\n## Configuration\n\nConfiguration for these subprojects consist of a collection of environment\nvariables for the various endpoints. These endpoints are configured using\ngoclouddev compatible URL strings. In these cases, documentation will be linked\nto and `DRIVER-Constructor` sections should be ignored in favour of `DRIVER`\nsections as these are appropriate to the configurations in place throughout\nthese subprojects. Note that not all drivers will be supported but they can be\nadded quite simply with a minor patch to the repository. See the addition of\nkafka for scheduler in\n[one line](https://github.com/ossf/package-analysis/commit/985ab76a67d29d2fc8582b3920643e7eb963da8a#diff-8565ef29cfb886db7902792675eddce1e7a0ccfe33428a59e7f2e365b354af88R12).\n\nAn example of these variables can be found in the\n[e2e example docker-compose](configs/e2e/docker-compose.yml).\n\n### Analysis\n\n`OSSMALWARE_WORKER_SUBSCRIPTION` - Can be used to set the subscription URL for\nthe data coming out of scheduler. Values should follow\n[goclouddev subscriptions](https://gocloud.dev/howto/pubsub/subscribe/).\n\n`OSSF_MALWARE_ANALYSIS_RESULTS` - **OPTIONAL**: Can be used to set the bucket\nURL to publish results to. Values should follow\n[goclouddev buckets](https://gocloud.dev/howto/blob/).\n\n`OSSF_MALWARE_ANALYSIS_PACKAGES` - **OPTIONAL**: Can be used to set the bucket\nURL to get custom uploaded packages from. Values should follow\n[goclouddev buckets](https://gocloud.dev/howto/blob/).\n\n`OSSF_MALWARE_NOTIFICATION_TOPIC` - **OPTIONAL**: Can be used to set the topic URL to\npublish messages for consumption after a new package analysis is complete. Values should follow\n[goclouddev publishing](https://gocloud.dev/howto/pubsub/publish/).\n\n### Scheduler\n\n`OSSMALWARE_WORKER_TOPIC` - Can be used to set the topic URL to publish data for\nconsumption by Analysis workers. Values should follow\n[goclouddev publishing](https://gocloud.dev/howto/pubsub/publish/).\n\n`OSSMALWARE_SUBSCRIPTION_URL` - Can be used to set the subscription URL for the\ndata coming out of [package-feeds](https://github.com/ossf/package-feeds).\nValues should follow\n[goclouddev subscriptions](https://gocloud.dev/howto/pubsub/subscribe/).\n\n## Local Analysis\n\nTo run the analysis code locally, the easiest way is to use the Docker image\n`gcr.io/ossf-malware-analysis/analysis`. This can be built with\n`make build/image/analysis`, or the public images can be used instead.\n\nThis container uses `podman` to run a nested, sandboxed ([gVisor]) container for\nanalysis.\n\nThe commands below will dump the JSON results to `/tmp/results`\nand full logs to `/tmp/dockertmp`.\n\n[gVisor]: https://gvisor.dev/\n\n### Live package\n\nTo run this on a live package (e.g. the latest version of the \"Django\" package on\n[pypi.org](https://pypi.org))\n\n```bash\n$ scripts/run_analysis.sh -ecosystem pypi -package Django\n```\n\nOr with a specific version\n\n```bash\n$ scripts/run_analysis.sh -ecosystem pypi -package Django -version 4.1.3\n```\n\n### Local package\n\nTo run analysis on a local PyPi package named 'test',\nlocated in local archive `/path/to/test.whl`\n\n\n```bash\n$ scripts/run_analysis.sh -ecosystem pypi -package test -local /path/to/test.whl\n```\n\n### Docker notes\n\n(Note: these options are handled by the `scripts/run_analysis.sh` script).\n\n`--privileged` and a compatible filesystem are required to properly run nested\ncontainers. `-v /var/lib/containers:/var/lib/containers` is also used as it\nallows caching the sandbox images and supports local developement.\n\n## Development\n\n### Testing\nSee `sample_packages/README.md` for how to use a sample package that simulates malicious activity for testing purposes.\n\n### Required Dependencies\n\n- Go v1.23.1\n- Docker\n\n# Contributing\n\nIf you want to get involved or have ideas you'd like to chat about, we discuss this project in the [OSSF Securing Critical Projects Working Group](https://github.com/ossf/wg-securing-critical-projects) meetings.\n\nSee the [Community Calendar](https://calendar.google.com/calendar?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for the schedule and meeting invitations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossf%2Fpackage-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fossf%2Fpackage-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossf%2Fpackage-analysis/lists"}