diff --git a/.github/workflows/docs-workflow.yml b/.github/workflows/docs-workflow.yml new file mode 100644 index 0000000..84d08d3 --- /dev/null +++ b/.github/workflows/docs-workflow.yml @@ -0,0 +1,163 @@ +name: PowerShell Documentation + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + schedule: + - cron: '0 0 * * 5' # Weekly run on Friday at midnight + +jobs: + validate: + name: Validate PowerShell Scripts + runs-on: windows-latest + + steps: + - uses: actions/checkout@v3 + + - name: Install PSScriptAnalyzer + shell: pwsh + run: | + Set-PSRepository PSGallery -InstallationPolicy Trusted + Install-Module -Name PSScriptAnalyzer -Force + + - name: Lint with PSScriptAnalyzer + shell: pwsh + run: | + $results = Invoke-ScriptAnalyzer -Path ./commands -Recurse -Settings PSGallery + $results | Format-Table -AutoSize + if ($results) { + Write-Warning "PSScriptAnalyzer found issues. Please review them." + $results | Format-Table -AutoSize + } + + - name: Check PowerShell syntax + shell: pwsh + run: | + $files = Get-ChildItem -Path ./commands -Include *.ps1,*.psm1 -Recurse + foreach ($file in $files) { + $syntaxErrors = $null + $null = [System.Management.Automation.PSParser]::Tokenize((Get-Content -Path $file.FullName -Raw), [ref]$syntaxErrors) + if ($syntaxErrors.Count -gt 0) { + Write-Error "Syntax errors in $($file.FullName)" + $syntaxErrors | Format-Table -AutoSize + exit 1 + } + } + + build-docs: + name: Build Documentation + runs-on: ubuntu-latest + needs: validate + + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material pymdown-extensions + + - name: Generate command documentation + shell: bash + run: | + mkdir -p docs/commands + for file in commands/*.ps1; do + filename=$(basename "$file" .ps1) + echo "# $filename Commands" > "docs/commands/${filename}.md" + echo '```powershell' >> "docs/commands/${filename}.md" + cat "$file" >> "docs/commands/${filename}.md" + echo '```' >> "docs/commands/${filename}.md" + done + + - name: Build documentation + run: | + mkdocs build + + - name: Deploy to GitHub Pages + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site + + update-readme: + name: Update README with Command Count + runs-on: ubuntu-latest + needs: validate + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + + steps: + - uses: actions/checkout@v3 + + - name: Count commands + id: count + shell: bash + run: | + TOTAL_COUNT=$(grep -r "function " ./commands | wc -l) + echo "TOTAL_COUNT=$TOTAL_COUNT" >> $GITHUB_ENV + + AD_COUNT=$(grep -r "function " ./commands/active-directory.ps1 2>/dev/null | wc -l || echo "0") + echo "AD_COUNT=$AD_COUNT" >> $GITHUB_ENV + + AZURE_COUNT=$(grep -r "function " ./commands/azure-m365.ps1 2>/dev/null | wc -l || echo "0") + echo "AZURE_COUNT=$AZURE_COUNT" >> $GITHUB_ENV + + SECURITY_COUNT=$(grep -r "function " ./commands/security.ps1 2>/dev/null | wc -l || echo "0") + echo "SECURITY_COUNT=$SECURITY_COUNT" >> $GITHUB_ENV + + - name: Update README + uses: actions/github-script@v6 + with: + script: | + const fs = require('fs'); + const readme = fs.readFileSync('README.md', 'utf8'); + + // Update command count in the description + let updatedReadme = readme.replace( + /📘 Curated PowerShell command library for IT professionals - \d+\+ ready-to-use commands/, + `📘 Curated PowerShell command library for IT professionals - ${process.env.TOTAL_COUNT}+ ready-to-use commands` + ); + + // Add command count by category if not present + if (!updatedReadme.includes('## Command Count')) { + updatedReadme += `\n\n## Command Count\n\n`; + updatedReadme += `- **Total Commands**: ${process.env.TOTAL_COUNT}\n`; + updatedReadme += `- **Active Directory**: ${process.env.AD_COUNT}\n`; + updatedReadme += `- **Azure & Microsoft 365**: ${process.env.AZURE_COUNT}\n`; + updatedReadme += `- **Security**: ${process.env.SECURITY_COUNT}\n`; + } else { + // Update existing command count section + updatedReadme = updatedReadme.replace( + /- \*\*Total Commands\*\*: \d+/, + `- **Total Commands**: ${process.env.TOTAL_COUNT}` + ); + updatedReadme = updatedReadme.replace( + /- \*\*Active Directory\*\*: \d+/, + `- **Active Directory**: ${process.env.AD_COUNT}` + ); + updatedReadme = updatedReadme.replace( + /- \*\*Azure & Microsoft 365\*\*: \d+/, + `- **Azure & Microsoft 365**: ${process.env.AZURE_COUNT}` + ); + updatedReadme = updatedReadme.replace( + /- \*\*Security\*\*: \d+/, + `- **Security**: ${process.env.SECURITY_COUNT}` + ); + } + + fs.writeFileSync('README.md', updatedReadme); + + - name: Commit and push if changed + run: | + git config --global user.name 'GitHub Actions' + git config --global user.email 'actions@github.com' + git add README.md + git diff --quiet && git diff --staged --quiet || git commit -m "Update command count in README [skip ci]" + git push \ No newline at end of file diff --git a/README.md b/README.md index 97c2cc7..2c5c69c 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,187 @@ -# PowerShell Command Reference +# PowerShell Command Reference Library -This repository serves as a curated reference of PowerShell commands categorized by use case. It is designed for quick lookup and practical usage, especially for IT administrators and engineers. +![PowerShell](https://img.shields.io/badge/PowerShell-5.1%2B-blue) +![Commands](https://img.shields.io/badge/Commands-100%2B-green) +![MIT License](https://img.shields.io/badge/license-MIT-blue.svg) -## Categories -- Active Directory -- Azure and Microsoft 365 -- File System and Disk Management -- Networking and Firewall -- Scheduled Tasks and Automation -- Security and Permissions +> 📘 Curated PowerShell command library for IT professionals - 100+ ready-to-use commands for AD, Azure, security, and automation tasks -## Usage -Each `.ps1` file includes a set of command snippets grouped by category. You can copy/paste them into your PowerShell terminal or integrate them into scripts as needed. +## 🚀 Overview -## Contributing -Pull requests are welcome. Please group related commands under the appropriate `.ps1` file or request a new category if needed. +This repository provides a comprehensive collection of PowerShell commands and scripts organized by category for IT professionals, system administrators, and cloud engineers. Each command includes detailed explanations, usage examples, and best practices. -## License -MIT License. See `LICENSE` for details. +## 📋 Categories -## Author -Jaquan Watson -[Portfolio](https://jaquanwatson.github.io) | [GitHub](https://github.com/jaquanwatson) + + + + + + + + + + + + + + + + + + + + + + + + + +
🔹 Active DirectoryUser management, group policies, domain operations, security groups
☁️ Azure & Microsoft 365Resource management, tenant administration, Exchange Online, SharePoint
💾 File System & StorageFile operations, disk management, permissions, backup/restore
🌐 NetworkingDNS, DHCP, firewall configuration, connectivity testing
🔒 Security & ComplianceAuditing, permissions, encryption, compliance reporting
⚙️ AutomationScheduled tasks, workflows, event triggers, reporting
+ +## 📖 How to Use This Repository + +### Command Files Structure + +Each category has its own `.ps1` file containing related commands: + +``` +commands/ +├── active-directory.ps1 +├── azure-m365.ps1 +├── file-system.ps1 +├── networking.ps1 +├── security.ps1 +└── automation.ps1 +``` + +### Documentation Structure + +Comprehensive documentation is available in the `docs/` folder: + +``` +docs/ +├── active-directory.md +├── azure.md +├── file-system.md +├── networking.md +├── security.md +└── automation.md +``` + +### Usage Examples + +Each command includes: +- Purpose and description +- Required parameters +- Example usage +- Expected output +- Common use cases + +Example from `active-directory.ps1`: + +```powershell +# Get all disabled user accounts in Active Directory +# Usage: Lists all disabled user accounts with their last logon time +function Get-DisabledADUsers { + Get-ADUser -Filter {Enabled -eq $false} -Properties LastLogonDate, DisplayName | + Select-Object DisplayName, SamAccountName, LastLogonDate | + Sort-Object LastLogonDate +} + +# Example output: +# DisplayName SamAccountName LastLogonDate +# ----------- ------------- ------------- +# John Smith jsmith 2023-05-15 10:30:45 +# Jane Doe jdoe 2023-06-22 14:15:30 +``` + +## 🔍 Quick Reference + +### Most Popular Commands + +
+Active Directory Commands + +```powershell +# Get all locked out accounts +Search-ADAccount -LockedOut | Select-Object Name, SamAccountName + +# Reset user password +Set-ADAccountPassword -Identity "username" -Reset -NewPassword (ConvertTo-SecureString -AsPlainText "NewPassword" -Force) + +# Get inactive users (90+ days) +$date = (Get-Date).AddDays(-90) +Get-ADUser -Filter {LastLogonTimeStamp -lt $date -and Enabled -eq $true} -Properties LastLogonTimeStamp | +Select-Object Name, @{Name="LastLogon"; Expression={[DateTime]::FromFileTime($_.lastLogonTimestamp)}} +``` +
+ +
+Azure & Microsoft 365 Commands + +```powershell +# Connect to Microsoft 365 +Connect-MsolService + +# Get all licensed users +Get-MsolUser -All | Where-Object {$_.isLicensed -eq $true} | Select-Object DisplayName, UserPrincipalName, Licenses + +# Get Azure AD sign-in logs +Get-AzureADAuditSignInLogs -Top 10 | Select-Object UserPrincipalName, AppDisplayName, Status, CreatedDateTime +``` +
+ +
+Security Commands + +```powershell +# Get failed login attempts +Get-EventLog -LogName Security -InstanceId 4625 -Newest 10 + +# Check file permissions +Get-Acl -Path "C:\path\to\file.txt" | Format-List + +# Export security audit +Get-WinEvent -FilterHashtable @{LogName='Security'; ID=4624,4625,4634} -MaxEvents 100 | +Export-Csv -Path "C:\security_audit.csv" -NoTypeInformation +``` +
+ +## 🛠️ Contributing + +Contributions are welcome! Please follow these steps: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/new-commands`) +3. Add your commands with proper documentation +4. Commit your changes (`git commit -m 'Add networking commands'`) +5. Push to the branch (`git push origin feature/new-commands`) +6. Open a Pull Request + +### Contribution Guidelines + +- Include detailed comments for each command +- Provide practical examples +- Test all commands before submitting +- Follow PowerShell best practices +- Group related commands together + +## 📝 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 👤 Author + +**Jaquan Watson** +- GitHub: [@jaquanwatson](https://github.com/jaquanwatson) +- LinkedIn: [jaquanwatson](https://linkedin.com/in/jaquanwatson) +- Email: jqwatson96@gmail.com + +--- + +
+ +⭐ **Found this useful? Star this repository!** ⭐ + +
\ No newline at end of file