LaraC2 Shell -- MDE Live Response Interactive Shell

Cross-platform interactive shell for Microsoft Defender for Endpoint
Live Response. Dual API mode (Internal portal + Official public), 7
auth methods, 25 native LR commands plus arbitrary command execution
via auto-uploaded B64 executor stubs, cross-OS targeting (Windows,
Linux, macOS), transparent rate limiting and session lifecycle.

MIT License. See README.md for full documentation.

Author: akefallonitis

.config/PSScriptAnalyzerSettings.psd1

@@ -0,0 +1,46 @@
+@{
+    Severity = @('Error', 'Warning')
+
+    ExcludeRules = @(
+        # We use Write-Host intentionally for colored shell output.
+        'PSAvoidUsingWriteHost',
+
+        # Private functions use _ prefix naming convention by design.
+        'PSUseApprovedVerbs',
+
+        # ShouldProcess not needed for our internal state functions.
+        'PSUseShouldProcessForStateChangingFunctions',
+
+        # ConvertTo-SecureString used for internal auth flows where the source
+        # is already in-memory plaintext from the operator's interactive prompt.
+        'PSAvoidUsingConvertToSecureStringWithPlainText',
+
+        # We use positional parameters in internal helpers for brevity.
+        'PSAvoidUsingPositionalParameters',
+
+        # _Int_ConnectByCredential intentionally accepts Username+Password for
+        # Entra credential auth flow; the same entry point also triggers the
+        # plain-text parameter warning for the same reason.
+        'PSAvoidUsingUsernameAndPasswordParams',
+        'PSAvoidUsingPlainTextForPassword',
+
+        # Empty catch blocks are used intentionally for non-fatal cleanup and
+        # best-effort state updates (rate limiter, library cleanup, auth
+        # fallback). Making any of these fail loudly would break the shell
+        # for transient conditions they are specifically designed to ignore.
+        'PSAvoidUsingEmptyCatchBlock',
+
+        # Functions that return collections use plural nouns (Get-MDEMachines,
+        # Get-MDEActions, Show-MDEMachines, etc.). This matches the MDE API
+        # surface and how PowerShell itself handles collection-returning
+        # cmdlets (Get-Process, Get-Service).
+        'PSUseSingularNouns'
+    )
+
+    Rules = @{
+        PSUseCompatibleSyntax = @{
+            Enable         = $true
+            TargetVersions = @('7.0')
+        }
+    }
+}

.gitattributes

@@ -0,0 +1,3 @@
+*.yml text eol=lf
+*.yaml text eol=lf
+*.sh text eol=lf

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Code owners -- automatically requested for review on PRs
+* @akefallonitis

.github/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to LaraC2 Shell
+
+Thank you for your interest in contributing. This document provides guidelines for contributing to LaraC2 Shell.
+
+## Getting Started
+
+1. **Fork** the repository
+2. **Clone** your fork locally
+3. **Create a branch** for your changes: `git checkout -b feature/my-feature`
+4. **Make your changes** and add tests
+5. **Run tests** to verify nothing is broken
+6. **Commit** with a clear message
+7. **Push** and open a Pull Request
+
+## Development Setup
+
+```powershell
+# Prerequisites: PowerShell Core 7.0+, Pester 5.x, PSScriptAnalyzer
+Install-Module -Name Pester              -MinimumVersion 5.0 -Scope CurrentUser
+Install-Module -Name PSScriptAnalyzer    -Scope CurrentUser
+
+# Run offline tests (no MDE tenant needed)
+pwsh -NoProfile -Command "Invoke-Pester -Path tests/shell/LaraC2Shell.Offline.Tests.ps1 -Output Detailed"
+
+# Run the same lint CI runs
+pwsh -NoProfile -Command "Invoke-ScriptAnalyzer -Path ./shell -Recurse -Settings ./.config/PSScriptAnalyzerSettings.psd1"
+```
+
+## Code Style
+
+- Follow existing patterns in the codebase
+- Use `[CmdletBinding()]` and proper parameter validation
+- Include `.SYNOPSIS` and `.PARAMETER` documentation for public functions
+- Private helper functions use `_` prefix (e.g., `_Out-Info`, `_Parse-Response`)
+- PSScriptAnalyzer runs on every PR -- check `.config/PSScriptAnalyzerSettings.psd1` for rules
+
+## Testing
+
+- **All PRs must pass offline tests** (712+ tests, no credentials needed) and the PSScriptAnalyzer lint job
+- Add tests for new features or bug fixes
+- Test files go in `tests/shell/` following the existing naming convention
+- Online tests require an MDE tenant and are run separately
+
+## Pull Request Process
+
+1. Ensure all offline tests pass
+2. Update documentation if your change affects user-facing behavior
+3. Keep PRs focused -- one feature or fix per PR
+4. Describe what your PR does and why in the description
+
+## Reporting Issues
+
+- Use GitHub Issues with the provided templates
+- Include: PowerShell version, OS, error messages, steps to reproduce
+- For security vulnerabilities, follow [SECURITY.md](../SECURITY.md) -- do not open a public issue
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: '[BUG] '
+labels: bug
+---
+
+## Description
+
+<!-- Clear description of the bug -->
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+<!-- What should have happened -->
+
+## Actual Behavior
+
+<!-- What actually happened. Include error messages. -->
+
+## Environment
+
+- **OS**: <!-- e.g., Windows 11, Ubuntu 22.04, macOS 14 -->
+- **PowerShell version**: <!-- output of $PSVersionTable.PSVersion -->
+- **API mode**: <!-- Official / Internal -->
+- **Auth method**: <!-- e.g., client credentials, device code, TOTP -->
+
+## Additional Context
+
+<!-- Screenshots, logs, config excerpts (redact secrets!) -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: '[FEATURE] '
+labels: enhancement
+---
+
+## Description
+
+<!-- What feature would you like to see? -->
+
+## Use Case
+
+<!-- Why is this feature needed? What problem does it solve? -->
+
+## Proposed Solution
+
+<!-- How should it work? Include examples if possible. -->
+
+## Alternatives Considered
+
+<!-- Any alternative approaches you've considered? -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- What does this PR do? Why is this change needed? -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring (no functional change)
+- [ ] Test coverage improvement
+
+## Testing
+
+- [ ] All offline tests pass (`Invoke-Pester -Path tests/shell/LaraC2Shell.Offline.Tests.ps1`)
+- [ ] New tests added for changed functionality
+- [ ] Tested on: Windows / Linux / macOS (delete as appropriate)
+
+## Checklist
+
+- [ ] Code follows existing style and patterns
+- [ ] Documentation updated (if user-facing change)
+- [ ] No credentials, secrets, or machine-specific data committed
+- [ ] PSScriptAnalyzer passes (checked by CI)

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Keep GitHub Actions versions patched automatically.
+# Docs: https://docs.github.com/en/code-security/dependabot/working-with-dependabot
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"