{"id":21888643,"url":"https://github.com/swisscom/powergrr","last_synced_at":"2025-04-15T10:21:12.367Z","repository":{"id":40302514,"uuid":"97600038","full_name":"swisscom/PowerGRR","owner":"swisscom","description":"PowerGRR is an API client library in PowerShell working on Windows, Linux and macOS for GRR automation and scripting.","archived":false,"fork":false,"pushed_at":"2022-03-18T10:18:29.000Z","size":379,"stargazers_count":56,"open_issues_count":1,"forks_count":7,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-15T10:20:19.998Z","etag":null,"topics":["grr","incident-response","powershell","powershell-module","threat-hunting"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swisscom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-18T13:14:29.000Z","updated_at":"2023-08-26T18:23:48.000Z","dependencies_parsed_at":"2022-09-07T15:50:10.344Z","dependency_job_id":null,"html_url":"https://github.com/swisscom/PowerGRR","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/swisscom%2FPowerGRR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2FPowerGRR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2FPowerGRR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2FPowerGRR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swisscom","download_url":"https://codeload.github.com/swisscom/PowerGRR/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249048828,"owners_count":21204317,"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":["grr","incident-response","powershell","powershell-module","threat-hunting"],"created_at":"2024-11-28T11:16:24.406Z","updated_at":"2025-04-15T10:21:12.349Z","avatar_url":"https://github.com/swisscom.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"![alt text](media/powergrr.png \"PowerGRR Logo\")\n\n# PowerGRR - PowerShell Module for GRR API\n\nPowerGRR is an API client library in PowerShell working on Windows, Linux and macOS for GRR automation and scripting.\n\nPlease see [Command Documentation](docs/PowerGRR.md), [Wiki](https://github.com/swisscom/PowerGRR/wiki) and\n[CHANGELOG](CHANGELOG.md).\n\n***\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [What is PowerGRR?](#what-is-powergrr)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Usage](#usage)\n    * [Import](#import)\n    * [Authentication](#authentication)\n    * [Cmdlets](#cmdlets)\n    * [Help](#help)\n    * [Example](#example)\n* [Contributing](#contributing)\n\n\u003c!-- vim-markdown-toc --\u003e\n***\n\n## What is PowerGRR? \n\nPowerGRR is a **PowerShell module for the\n[GRR](https://github.com/google/grr) API working on Windows, macOS and\nLinux**. GRR Rapid Response is an incident response framework focused on\nremote live forensics. PowerGRR allows working with flows, hunts, labels,\nartifacts, approvals and the search feature. Furthermore, it allows **working\nwith the computer names instead of the GRR internal client id**. This makes\nhandling and working with other tools more easy because often you just have\nthe computer names. PowerGRR also enables you to easily document your work in\ntext form which is then directly reusable by others.\n\nSome of the use cases where PowerGRR could speed up the work:\n* Start a flow on one or multiple clients and get flow results as PowerShell\n    object for easier filtering. Download collected files directly from\n    command line.\n* Create and start a new hunt and get the hunt info or results as PowerShell\n    objects. Download collected files directly from command line.\n* [Create a hunt or a client approval request and wait until they get valid](https://github.com/swisscom/powergrr/wiki#commands-for-using-the-grr-approval-system).\n* Add or remove a label on one or multiple clients based on a list of computer\n    names.\n* Add artifacts to or remove artifacts from the GRR artifact repository.\n* List clients, flows, hunts, artifacts, labels, client or hunt approvals and\n  filter them in different ways.\n* Build [IR scripts for common forensic workflows and start multiple hunts or\n    flows in one shot using multiple cmdlets inside a PowerShell script](https://github.com/swisscom/PowerGRR/wiki/Live-response-collection-script).\n\nThe following flow types are available for hunts and flows and the target group\nis chosen based on labels or the OS. See also [command\nhelp](https://github.com/swisscom/PowerGRR/blob/master/docs/Invoke-GRRFlow.md#description)\nfor the available flow types.\n* Netstat, ListProcesses, FileFinder, RegistryFinder, ExecutePythonHack, ArtifactCollectorFlow, YaraProcessScan\n\n## Installation\n\nUpdate March 2022: Install [PowerGRR from PowerShell Gallery](https://www.powershellgallery.com/packages/PowerGRR) was only supported until March 2022. Afterwards, only manual install through Github is provided. See [CHANGELOG](CHANGELOG.md) for more details about versions.\n   \n* Install PowerGRR from Github:\n\n    * Clone or download the repo into your module path folder, usually\n      _~\\Documents\\WindowsPowerShell\\modules_ on Windows or\n      _~/.local/share/powershell/Modules/_ on macOS (see _$env:PSModulePath_).\n    * Clone or download the files to any other folder (could also be a share).\n    * **Windows** Make sure to unblock the files when downloaded from the\n        Internet by opening the properties page of the .psd1 and .psm1 files and\n        checking \"Unblock\" at the bottom.\n\n    The location changes how the module is imported.\n\n## Configuration\n\n1. Create a 'powergrr-config.ps1' in the profile folder (`$env:USERPROFILE` or\n`$env:HOME`) or in the root folder of the module.\n1. Set the config variables as needed. \n   * **[MUST]** _$GRRUrl_: GRR server's URL.\n   * **[OPTIONAL]** _$GRRIgnoreCertificateErrors_: If set to $true certificate errors are ignored.\n   * **[OPTIONAL]** _$GRRClientCertIssuer_:  If set, the client certificate\n                    from the Windows cert store signed by the given issuer is used.\n   * **[OPTIONAL]** _$GRRClientCertFilePath_: If set, the client certificate\n                   file is used for the authentication.\n\nIt's also possible to set these variables in the console.\n\n**Example Configs**\n\n``` PowerShell\n$GRRUrl = \"https://grrserver.tld\"\n```\n\n``` PowerShell\n$GRRUrl = \"https://grrserver.tld\"\n$GRRClientCertIssuer = \"issuer of the certificate for client auth\"\n```\n\nIf you want to get crazy you could even use a config file file looking\nlike this if you need to constantly change the GRR config otherwise. You only\nneed to change the comment for the GRRUrl.\n\n``` powershell\n#$GRRUrl = \"https://main-grrserver.tld\"\n$GRRUrl = \"https://test-grrserver.tld\"\n$GRRIgnoreCertificateErrors = $( if ($GRRUrl -match \"test\") { $true } )\n$GRRClientCertIssuer = $( if ($GRRUrl -match \"main\") { \"certificate issuer\" } )\n```\n\n## Usage\n\nUse `command -\u003ctab\u003e` to tab between the available parameters or use \n`command -\u003cctrl+space\u003e` to display a list of all paremeters. Some commands \nuse dynamic parameters which are only available after selecting the main one, \ne.g. in `Invoke-GRRFlow` first choose your flow type with `-Flow ...` and then\nthe flow-specific parameters become available.\n\n### Import\n\nIf PowerGRR was saved inside the module path run the following command:\n```\nImport-Module PowerGRR -force\n```\n\nIf PowerGRR was saved outside the module path run the command:\n\n```\nImport-Module \u003cpath to module\u003e\\PowerGRR.psd1 -force\n```\n\n### Authentication\n\n1. Store your GRR credentials for any subsequent PowerGRR command or otherwise\nyou will be prompted when running the commands. Either provide the credentials\nwith `-Credential` in each command or use the variable `$GRRCredential` to set\nthe credentials which then will be used without the need for supplying\n`-Credential`.\n\n```powershell\n$GRRCredential = Microsoft.PowerShell.Security\\get-credential\n```\n\n2. If you use client certificate authentication set the corresponding config\nvariable as described in [Configuration](#configuration) above.\n\n### Cmdlets\n\nPlease see [docs](docs/PowerGRR.md) for the list of all available commands and the\n[wiki](https://github.com/swisscom/PowerGRR/wiki) for further information how\nyou could use and combine the different PowerGRR commands.\n\nUse the common parameters like _-WhatIf_ or _-Verbose_ for troubleshooting and to\nsee what the commands would do. _WhatIf_ is implemented for every function which\nmake any permanent change (e.g. start a flow, set a label, ...).\n\nList available PowerGRR commands.\n\n```powershell\nget-command -Module PowerGRR\n```\n\nList all PowerGRR commands for flows.\n\n```powershell\nget-command -Module PowerGRR | sls flow\n```\n\n### Help\n\nUse `help \u003ccommand\u003e` to get the help for a command.\n\n```powershell\nPS\u003e help Get-GRRHuntInfo\n\nNAME\n    Get-GRRHuntInfo\n\nOVERVIEW\n    Get hunt info for a specific hunt.\n\nSYNTAX\n    Get-GRRHuntInfo [[-HuntId] \u003cString\u003e] [-Credential] \u003cPSCredential\u003e [-ShowJSON] [\u003cCommonParameters\u003e]\n...\n```\n\nUse `help \u003ccommand\u003e -Examples` to get examples for a command.\n\n```powershell\nPS\u003e help Get-GRRHuntInfo -Examples\n\nNAME\n    Get-GRRHuntInfo\n\nOVERVIEW\n    Get hunt info for a specific hunt.\n\n    Example 1\n\n    PS C:\\\u003e Get-GRRHuntInfo \"H:AAAAAAAA\" -Credential $cred\n...\n```\n\n### Example\n\nThe following examples shows how you could combine the different PowerGRR functions\nto quickly label some clients, start a flow against them or a hunt based on a label\nand read the results. You can find more code snippets and ideas in the\n[wiki](https://github.com/swisscom/PowerGRR/wiki) and see section\n[help](#help) above how to use the help system in PowerShell.\n\nUse `$GRRCredential` for setting the credentials before running the commands\nand the parameter `-Credential` is not needed anymore for each command.\n\n```powershell\n# Read the client information to check LastSeenAt and the OSVersion\nGet-GRRClientIdFromComputerName -ComputerName WIN-DESKTOP01,MBP-LAPTOP02,WIN-DESKTOP03,WIN-DESKTOP04 `\n                                -Credential $creds\n \nComputerName    ClientId           LastSeenAt          OSVersion\n------------    --------           ----------          ---------\nWIN-DESKTOP01   C.aaaaaaaaaaaaaaaa 18.05.2017 15:48:17 10.0.10586\nWIN-DESKTOP01   C.xxxxxxxxxxxxxxxx 03.04.2017 14:55:37 6.1.7601\nMBP-LAPTOP02    C.bbbbbbbbbbbbbbbb 18.05.2017 15:49:12 16.6.0\nWIN-DESKTOP03   C.dddddddddddddddd 11.03.2017 10:23:51 10.0.10586\nWIN-DESKTOP04   C.eeeeeeeeeeeeeeee 11.03.2017 10:23:51 10.0.10586\n\n(Get-GRRClientIdFromComputerName WIN-DESKTOP01).clientid\n\n# Set a label for multiple hosts during incident response with the parameter\n# __ComputerName__\nSet-GRRLabel -ComputerName WIN-DESKTOP01, WIN-DESKTOP03, WIN-DESKTOP04 -Label INC02_Windows `\n             -Credential $creds\n\n# or through the pipeline\n\"MBP-LAPTOP02\" | Set-GRRLabel -Label INC02_macOS -Credential $creds\n\n# Now you can work with that label within GRR UI or in the shell. Use\n# -OnlyComputerName to only display the hostname instead of the full GRR client\n# object\n$clients = Find-GRRClientByLabel -SearchString INC01 -Credential $creds -OnlyComputerName\n\n# Start a flow on the affected clients\n$clients | Invoke-GRRFlow -flow RegistryFinder `\n                          -key \"HKEY_USERS/%%users.sid%%/Software/Microsoft/Windows/CurrentVersion/Run/*\" `\n                          -Credential $cred\n\n# Get flow results - see output of specific flow ids. Using\n# -OnlyPayload navigates directly to the payload section of the results\n# within the returned GRR object\n$ret = Get-GRRFlowResult -Credential $cred -ComputerName WIN-DESKTOP01 -FlowId \"F:11111111\" -OnlyPayload\n\n# Show only the registry paths from the returned GRR object. Sometimes the\n# output is base64 encoded. Get-GRRFlowResult decodes the string if\n# possible. \n$ret.stat_entry.registry_data\n\n# Alternative you can start a hunt against that label. The EmailAddress\n# parameter is optional and notifies you about the first hit. The OnlyUrl\n# parameter shows only the URL to the hunt.\n$HuntId = New-GRRHunt -HuntDescription \"Search for notepad.exe\" `\n            -Flow FileFinder `\n            -path \"c:\\notepad.exe\" `\n            -MatchMode MATCH_ALL `\n            -actiontype hash `\n            -RuleType label `\n            -Label INC01 `\n            -EmailAddress your@email.tld `\n            -Credential $creds `\n            -OnlyUrl `\n            -Verbose\n\n# If needed request an approval\n$ApprovalId = New-GRRHuntApproval -Credential $cred -HuntId H:AAAAAAAA -NotifiedUsers user1 `\n                    -Reason \"Hunting for notepad.exe - INC01\" -OnlyId\n\n# Start the hunt\nStart-GRRHunt -Credential $creds -HuntId $HuntId\n\n# Start the hunt after approval got within the given timeout\nStart-GRRHunt -HuntId $HuntId -Credential $creds -Wait -ApprovalId $ApprovalId -TimeoutInMinutes 15\n\n# Read hunt restuls\n$ret = Get-GRRHuntResult -Credential $cred -HuntId $HuntId\n\n# Inspect results\n$ret.items\n\n# Filter results as needed - e.g. see unique clients which were affected \n$ret.items.client_id | get-unique\n\n# Get unique computer names based on the list of client ids\n$ret.items.client_id | Get-GRRComputerNameFromClientId -Credential $cred | get-unique\n\n# Get unique file paths from a file finder hunt\n$ret.items.payload.stat_entry.pathspec.path | sort -u\n\n# Remove the label if you don't use it anymore\n$clients | Remove-GRRLabel -SearchString INC01 -$Credential $creds\n\n# Find specific artifact names for ArtifactCollectorFlow\n$ret = Get-GRRArtifact\n$ret | select -first 1\n\nName        : APTSources\nDescription : APT package sources list\nIsCustom    : False\nURLs        : http://manpages.ubuntu.com/manpages/trusty/en/man5/sources.list.5.html\nLabels      : {Configuration Files, System}\nSupportedOS : {Linux}\nType        : FILE\nAttributes  : @{paths=System.Object[]}\n\n$ret | ? { $_.description -match \"registry\" }\n\n# If you use a GRR API request for which there is no predefined function, \n# then use Invoke-GRRRequest with the specific API endpoint, as an example, \n# we list all flows of a given client\n$ret = Invoke-GRRRequest -Url /clients/$((Get-GRRClientIdFromComputerName WIN-DESKTOP01).clientid)/flows\n$ret.items\n```\n\n## Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md) for general guidelines and some inner\nworkings of PowerGRR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisscom%2Fpowergrr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswisscom%2Fpowergrr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisscom%2Fpowergrr/lists"}