Skip to content

Commit df1e922

Browse files
yordadevyordadev
committed
Initial Release 🎨
0 parents  commit df1e922

27 files changed

+9822
-0
lines changed

‎.github/workflows/dependency-review.yml

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependency Review Action
2+
#
3+
# This Action will scan dependency manifest files that change as part of a Pull Request, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
4+
#
5+
# Source repository: https://github.com/actions/dependency-review-action
6+
# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
7+
name: 'Dependency Review'
8+
on: [pull_request]
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
dependency-review:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: 'Checkout Repository'
18+
uses: actions/checkout@v3
19+
- name: 'Dependency Review'
20+
uses: actions/dependency-review-action@v2

‎.github/workflows/fix-php-code-style-issues.yml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Linter
2+
3+
on: [push]
4+
5+
jobs:
6+
php-code-styling:
7+
runs-on: ubuntu-latest
8+
9+
steps:
10+
- name: Checkout code
11+
uses: actions/checkout@v3
12+
with:
13+
ref: ${{ github.head_ref }}
14+
15+
- name: Fix PHP code style issues
16+
uses: aglipanci/[email protected]
17+
18+
- name: Commit changes
19+
uses: stefanzweifel/git-auto-commit-action@v4
20+
with:
21+
commit_message: Fix styling

‎.github/workflows/phpunit.yml

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: phpunit
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
run-tests:
9+
runs-on: ubuntu-latest
10+
strategy:
11+
fail-fast: false
12+
matrix:
13+
php: [8.1, 8.2]
14+
laravel: [9.*, 10.*]
15+
include:
16+
- laravel: 10.*
17+
testbench: 8
18+
- laravel: 9.*
19+
testbench: 7.*
20+
21+
name: PHP${{ matrix.php }} - Laravel ${{ matrix.laravel }}
22+
23+
steps:
24+
- name: Update apt
25+
run: sudo apt-get update --fix-missing
26+
27+
- name: Checkout code
28+
uses: actions/checkout@v2
29+
30+
- name: Setup PHP
31+
uses: shivammathur/setup-php@v2
32+
with:
33+
php-version: ${{ matrix.php }}
34+
coverage: none
35+
36+
- name: Setup Problem Matches
37+
run: |
38+
echo "::add-matcher::${{ runner.tool_cache }}/php.json"
39+
echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
40+
- name: Install dependencies
41+
run: |
42+
composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
43+
composer update --prefer-dist --no-interaction --no-suggest
44+
- name: Execute tests
45+
run: vendor/bin/phpunit

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/.phpunit.result.cache
2+
/coverage
3+
/vendor

‎Dockerfile

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM php:8.1-fpm
2+
3+
RUN apt-get update \
4+
&& apt-get -y install libzip-dev zlib1g-dev git zip unzip libicu-dev g++ libbz2-dev libmemcached-dev \
5+
&& apt-get clean; rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* \
6+
7+
RUN docker-php-ext-configure zip && docker-php-ext-install pdo pdo_mysql zip bz2 intl
8+
9+
# Get latest Composer
10+
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
11+
12+
# Set working directory
13+
WORKDIR /var/www
14+
15+
RUN chown -R www-data:www-data /var/www
16+
17+
# Expose port 9000 and start php-fpm server
18+
EXPOSE 9000
19+
CMD ["php-fpm"]

‎LICENSE.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2023 YorCreative
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+261
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
<br />
2+
<br />
3+
<div align="center">
4+
<a href="https://github.com/YorCreative">
5+
<img src="content/logo.png" alt="Logo" width="128" height="128">
6+
</a>
7+
</div>
8+
<h3 align="center">Laravel Scanator</h3>
9+
10+
<div align="center">
11+
<a href="https://github.com/YorCreative/Laravel-Scanator/blob/main/LICENSE.md"><img alt="GitHub license" src="https://img.shields.io/github/license/YorCreative/Laravel-Scanator"></a>
12+
<a href="https://github.com/YorCreative/Laravel-Scanator/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YorCreative/Laravel-Scanator"></a>
13+
<a href="https://github.com/YorCreative/Laravel-Scanator/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/YorCreative/Laravel-Scanator"></a>
14+
<a href="https://github.com/YorCreative/Laravel-Scanator/network"><img alt="GitHub forks" src="https://img.shields.io/github/forks/YorCreative/Laravel-Scanator"></a>
15+
<a href="https://github.com/YorCreative/Laravel-Scanator/actions/workflows/phpunit.yml"><img alt="PHPUnit" src="https://github.com/YorCreative/Laravel-Scanator/actions/workflows/phpunit.yml/badge.svg"></a>
16+
</div>
17+
18+
A Laravel package that provides functionalities for detecting sensitive information and patterns in the database, helping to ensure data privacy and security by empowering developers to easily integrate database scanning capabilities into their applications and take proactive measures to protect sensitive data.
19+
20+
## Installation
21+
22+
install the package via composer:
23+
24+
```bash
25+
composer require yorcreative/laravel-scanator
26+
```
27+
28+
Publish the assets.
29+
30+
```bash
31+
php artisan vendor:publish --provider="YorCreative\Scanator\ScanatorServiceProvider"
32+
php artisan vendor:publish --provider="YorCreative\Scanator\ScrubberServiceProvider"
33+
```
34+
35+
## Configuration
36+
37+
### Adjusting the Scanators Configuration File
38+
39+
Adjust the configuration file to suite your application, located in `/config/scanator.php`.
40+
41+
```php
42+
return [
43+
'sql' => [
44+
'ignore_tables' => [
45+
'failed_jobs',
46+
'migrations'
47+
],
48+
'ignore_columns' => [
49+
'id',
50+
'created_at',
51+
'updated_at'
52+
],
53+
'ignore_types' => [
54+
'timestamp'
55+
],
56+
'select' => [
57+
'low_limit' => 3,
58+
'high_limit' => 10
59+
],
60+
]
61+
];
62+
```
63+
64+
### Adjusting the Scrubber Configuration File
65+
66+
Adjust the `regex_loader` field to suite your application, located in `/config/scrubber.php`.
67+
For more information on the Scrubber configuration file, please see the source documentation [here](https://github.com/YorCreative/Laravel-Scrubber).
68+
69+
```php
70+
return [
71+
...
72+
'regex_loader' => ['*'], // Opt-in to specific regex classes OR include all with * wildcard.
73+
...
74+
];
75+
```
76+
77+
## Usage
78+
79+
This package is shipped without implementation. It is shipped as a tool and up to developers to choose how they implement to suite to applications needs.
80+
81+
### Detection Manager
82+
83+
The [DetectionManager](https://github.com/YorCreative/Laravel-Scanator/blob/dev/src/Support/DetectionManager.php#L8)
84+
class is an essential component of the Laravel Scanator package. It manages and stores the [Detections](https://github.com/YorCreative/Laravel-Scanator/blob/dev/src/Support/Detection.php#L9) during the scanning process.
85+
It provides methods to record detections, retrieve the list of detections, and obtain the scan start time.
86+
87+
### Full Database Scan
88+
This package ships with the ability to analyze and build out database schema and then scans for sensitive
89+
information excluding any tables, columns or types from the Scanator configuration file finally to return the
90+
Detection Manager class.
91+
92+
```php
93+
$detectionManager = Scanator::init();
94+
95+
$detections = $detectionManager->getDetections();
96+
```
97+
98+
### Selective Database Scan
99+
100+
This package ships with the ability to selectively scan tables.
101+
102+
```php
103+
$detectionManager = new DetectionManager();
104+
105+
Scanator::analyze($detectionManager, 'table_name', ['columns', 'to', 'scan']);
106+
107+
$detections = $detectionManager->getDetections();
108+
```
109+
110+
### Defining Excludable Tables
111+
112+
The configuration file of this package offers the functionality to define excludable tables, allowing you to exclude them from the scanning process.
113+
114+
115+
```php
116+
'ignore_tables' => [
117+
'failed_jobs',
118+
'migrations'
119+
],
120+
```
121+
122+
### Defining Excludable Columns
123+
124+
Similarly, you can define excludable columns within the configuration file to prevent the package from scanning them.
125+
126+
```php
127+
'ignore_columns' => [
128+
'id',
129+
'created_at',
130+
'updated_at'
131+
],
132+
```
133+
134+
### Defining Excludable Data Types
135+
136+
To further refine the scanning process, you can specify excludable data types in the configuration file.
137+
The package will then disregard these data types during scanning.
138+
139+
```php
140+
'ignore_types' => [
141+
'timestamp'
142+
],
143+
```
144+
145+
### Defining Sample Size
146+
147+
For greater control over the scanning procedure, the configuration file allows you to define the sample size extracted
148+
from each table.
149+
150+
```php
151+
'select' => [
152+
'low_limit' => 3,
153+
'high_limit' => 10
154+
],
155+
```
156+
157+
## Scrubber Documentation
158+
159+
This package builds on the [RegexRepository](https://github.com/YorCreative/Laravel-Scrubber/blob/main/src/Scrubber.php#L17) provided by the scrubber package. For complete documentation on the scrubber, see [here](https://github.com/YorCreative/Laravel-Scrubber)
160+
161+
### Regex Class Opt-in
162+
163+
You have the ability through the scrubber configuration file to define what regex classes you want loaded into the application
164+
when it is bootstrapped. By default, this package ships with a wildcard value.
165+
166+
### Regex Collection & Defining Opt-in
167+
168+
To opt in, utilize the static properties on
169+
the [RegexCollection](https://github.com/YorCreative/Laravel-Scrubber/blob/main/src/Repositories/RegexCollection.php)
170+
class.
171+
172+
```php
173+
'regex_loader' => [
174+
RegexCollection::$GOOGLE_API,
175+
RegexCollection::$AUTHORIZATION_BEARER,
176+
RegexCollection::$CREDIT_CARD_AMERICAN_EXPRESS,
177+
RegexCollection::$CREDIT_CARD_DISCOVER,
178+
RegexCollection::$CREDIT_CARD_VISA,
179+
RegexCollection::$JSON_WEB_TOKEN
180+
],
181+
```
182+
183+
### Creating Custom Extended Classes
184+
185+
The Scrubber package ships with a command to create custom extended classes and allows further refining of database scans for the Scanator.
186+
187+
```bash
188+
php artisan make:regex-class {name}
189+
```
190+
191+
This command will create a stubbed out class in `App\Scrubber\RegexCollection`. The Scrubber package will autoload
192+
everything from the `App\Scrubber\RegexCollection` folder with the wildcard value on the `regex_loader` array in the
193+
scrubber config file. You will need to provide a `Regex Pattern` and a `Testable String` for the class.
194+
195+
### Opting Into Custom Extended Classes
196+
197+
The `regex_loader` array takes strings, not objects. To opt in to specific custom extended regex classes, define the
198+
class name as a string.
199+
200+
For example if I have a custom extended class as such:
201+
202+
```php
203+
<?php
204+
205+
namespace App\Scrubber\RegexCollection;
206+
207+
use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
208+
209+
class TestRegex implements RegexCollectionInterface
210+
{
211+
public function getPattern(): string
212+
{
213+
/**
214+
* @todo
215+
* @note return a regex pattern to detect a specific piece of sensitive data.
216+
*/
217+
return '(?<=basic) [a-zA-Z0-9=:\\+\/-]{5,100}';
218+
}
219+
220+
public function getTestableString(): string
221+
{
222+
/**
223+
* @todo
224+
* @note return a string that can be used to verify the regex pattern provided.
225+
*/
226+
return 'basic f9Iu+YwMiJEsQu/vBHlbUNZRkN/ihdB1sNTU';
227+
}
228+
229+
public function isSecret(): bool
230+
{
231+
return false;
232+
}
233+
}
234+
```
235+
236+
The `regex_loader` array should be defined as such:
237+
238+
```php
239+
'regex_loader' => [
240+
RegexCollection::$GOOGLE_API,
241+
RegexCollection::$AUTHORIZATION_BEARER,
242+
RegexCollection::$CREDIT_CARD_AMERICAN_EXPRESS,
243+
RegexCollection::$CREDIT_CARD_DISCOVER,
244+
RegexCollection::$CREDIT_CARD_VISA,
245+
RegexCollection::$JSON_WEB_TOKEN,
246+
'TestRegex'
247+
],
248+
```
249+
250+
## Testing
251+
252+
```bash
253+
composer test
254+
```
255+
256+
## Credits
257+
258+
- [Yorda](https://github.com/yordadev)
259+
- [All Scanator Contributors](../../contributors)
260+
- [All Scrubber Contributors](https://github.com/YorCreative/Laravel-Scrubber/graphs/contributors)
261+

0 commit comments

Comments
 (0)