{"id":25506518,"url":"https://github.com/blackducksoftware/perceptor","last_synced_at":"2025-04-10T11:52:03.555Z","repository":{"id":127466903,"uuid":"120643958","full_name":"blackducksoftware/perceptor","owner":"blackducksoftware","description":"An open source,  cloud native toolkit for threat detection and mitigation","archived":false,"fork":false,"pushed_at":"2020-03-30T02:57:27.000Z","size":130084,"stargazers_count":19,"open_issues_count":7,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-24T10:45:38.239Z","etag":null,"topics":["golang","image","kubernetes","openshift","pod"],"latest_commit_sha":null,"homepage":"","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/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,"governance":null}},"created_at":"2018-02-07T16:55:13.000Z","updated_at":"2024-02-10T08:18:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"2bb91e99-15ae-43c6-b2d1-ad39e0da192f","html_url":"https://github.com/blackducksoftware/perceptor","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fperceptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fperceptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fperceptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackducksoftware%2Fperceptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackducksoftware","download_url":"https://codeload.github.com/blackducksoftware/perceptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248215191,"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":["golang","image","kubernetes","openshift","pod"],"created_at":"2025-02-19T06:58:15.637Z","updated_at":"2025-04-10T11:52:03.536Z","avatar_url":"https://github.com/blackducksoftware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/blackducksoftware/perceptor.svg?branch=master)](https://travis-ci.com/blackducksoftware/perceptor)\n\n# Perceptor\n\nPerceptor is an API server and event handler for consuming, storing, and queueing various workloads associated with responding to events that occur in distributed orchestration systems.  Canonically, it manages information related to container events that happen in cloud native orchestration systems (i.e. openshift, kubernetes, ...).\n\n# Perceptor core\n\nThis maintains a model which is essentially a join of the pods and images currently running in the system,\nand the information relating to those images from the hub.\n\nIt contains business logic for deciding when and what to scan, and provides a REST API for perceivers\nand scanners to communicate with it.\n\n\n## REST API\n\nThe Perceptor REST API can be consumed from any programming language.  We have [a Swagger specification](./api/perceptor-swagger-spec.json).  Check out [this online viewer](http://editor2.swagger.io) or [this online viewer](https://editor.swagger.io/) to get a nice UI.\n\nModifications to the REST API or data model should be made with great care in order to maintain backward compatibility. REST API change checklist:\n\n - The [swagger specification](./api/perceptor-swagger-spec.json) must be modified\n - The updated swagger specification must be present as part of the PR containing the modifications to the server\n\n**TODO**: Automatically generate server stubs from the swagger specification.\n \n# Perceivers\n\nPerceivers are workers that notify Perceptor of events, and respond to information that Perceptor acquires about those events.\n\nPerceivers are the canonical extension point to a Perceptor-based deployment to support new platforms and orchestration systems.  If you want to build one for your own platform, or customize the way cluster events are processed, check out [our Perceivers repo](https://github.com/blackducksoftware/perceivers) to learn more about them!\n\nPerceivers are responsible for interacting with the platform machinery, finding events and information of interest, and forwarding those to Perceptor.  Perceivers are also responsible for taking action based on the scan results available in Perceptor -- whether creating alerts, or writing information into Kubernetes objects.\n\nBy splitting perceivers into a separate pod, we gain two things:\n - platform independence of the Perceptor core.  Perceivers require a relatively small amount of code,\n   and are the only component that needs to be changed in order to support a new platform.\n - on openshift, perceivers require special permissions in order to be able to talk to the APIServer\n   and watch pod and image events\n\n# Scanners\n\nScanners are responsible for performing scan jobs by pulling from the Perceptor scan queue.  They do this by using a Black Duck Hub scan client and a running Black Duck Hub.  While perceptor scanners can be scaled, the hub itself remains a bottleneck.\n\n# Developing Perceptor!\n\n## Development Environment Setup\n\n1. Install gimme:\n\n```\ncurl -sL -o ~/bin/gimme https://raw.githubusercontent.com/travis-ci/gimme/master/gimme\nchmod +x ~/bin/gimme\nexport PATH=$PATH:~/bin/\ngimme 1.11\n```\n\n2. If necessary, set up your `GOPATH` and `GOROOT` environment variables.\n\n3. Create a directory based off your GOPATH for Perceptor:\n\n```\ncd $GOPATH\nmkdir -p src/github.com/blackducksoftware\ncd go/src/github.com/blackducksoftware\n```\n\n4. Clone the Perceptor repo:\n\n```\ngit clone https://github.com/blackducksoftware/perceptor.git\n```\n\n5. if using Atom, install the go-plus Atom package\n\n## Building\n\nCheck out [the makefile](./Makefile) -- from the root directory, run:\n\n    make\n    \nTo run tests:\n\n    make test\n    \nTo run standard go linters:\n\n    make lint\n\n## Continuous Integration\n\nWe build images, per commit, using cloud build files.  We're open to changing our build artifacts over time; take a look at [cloudbuild.yaml](./cloudbuild.yaml).\n\n## Running\n\nCheck out [Protoform](https://github.com/blackducksoftware/perceptor-protoform/)!\n\n## Development Policy\n\nPerceptor embraces the traditional values of open source projects in the Apache and CNCF communities, and emphasizes ideas and community over the code itself.\n\n## See a place to improve things?\n\nPlease create an issue -- better yet, accompanied with a pull request-- if you have any ideas for metrics, features, tests, or anything else related to Perceptor.\n\n## Sticking with golang Standards\n\nWe follow the same standards for golang as are followed in the moby project, the kubernetes project, and other major golang projects.  \n\nWe embrace modern golang idioms including usage of viper for configuration and dep for dependencies.\n\n## Testing your patches\n\nWe enable travis-ci for builds, which runs all the unit tests associated with your patches.  Make sure you submit code with unit tests when possible and verify your tests pass in your pull request.  If there are any issues with travis, file an issue and assign it to Jay (jayunit100) and Senthil (msenmurgan).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackducksoftware%2Fperceptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackducksoftware%2Fperceptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackducksoftware%2Fperceptor/lists"}