Credit: This is a fork of the original NPK project created by c6fc. All core functionality and features are preserved from the original work.

We forked the original NPK library to add enhanced security features that prevent public access to the APIs and Dashboard. This version implements IP-based access controls at the AWS infrastructure level to ensure your NPK deployment is only accessible from authorized networks.

NPK is a distributed hash-cracking platform built entirely of serverless components in AWS including Cognito, DynamoDB, and S3.

Let's face it - even the beastliest cracking rig spends a lot of time at idle. You sink a ton of money up front on hardware, then have the electricity bill to deal with. NPK lets you leverage extremely powerful hash cracking with the 'pay-as-you-go' benefits of AWS. For example, you can crank out 336 GH/s of NTLM for a mere $1/hr and scale it however you want. NPK was also designed to fit easily within the free tier while you're not using it! Without the free tier, it'll still cost less than $1 per MONTH to have online!

Install the security-enhanced version with a simple one-liner in AWS CloudShell:

source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

The One-Liner Installation Command:

• Downloads and executes the installer script directly from GitHub in one step
• Uses curl to fetch the script and source to run it immediately in your current shell

The Installation Script (bashguru_install.sh):

1. Prepares your environment in AWS CloudShell
2. Prompts for IP restrictions - asks which IP addresses should be allowed to access NPK
3. Uses your current IP as a default if no IPs are specified
4. Offers VPC EC2 Endpoint tagging - optional tagging for compliance and cost allocation tracking
5. Creates a settings file (npk-settings.json) with your security preferences
6. Downloads the secure NPK repository from the bashguru fork
7. Configures your deployment with dynamic IP-based access controls and optional VPC tagging

This approach ensures your NPK deployment is secure from the start, with access limited to only your authorized IPs.

1. Log into AWS Console and open CloudShell

2. Run the custom installation script:

   source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

3. Follow the installation wizard prompts:

   • Either select none to have receive a generated Cloudfront URL or select your custom domain name when asked
   • Configure IP restrictions
   • Set up VPC EC2 Endpoint tags (optional)
   • Complete the remaining configuration options

When the deploy finishes, you'll be dropped to a custom prompt, indicating that NPK is deployed and CloudShell is connected to it.

For original NPK documentation, see the original installation guide.

Take the trial-and-error out of complex attack types with the intuitive campaign builder. With a couple clicks you can create advanced campaigns that even advanced Hashcat users would struggle to emulate.

Take the guess-work out of your campaigns. See how far you'll get and how much it will cost before starting the campaign.

GPU instances are expensive. Runaway GPU instances are EXTREMELY expensive. NPK will enforce a maximum campaign price limit, and was designed to prevent runaway instances even with a complete failure of the management plane.

NPK supports multiple users, with strict separation of data, campaigns, and results between each user. It can optionally integrate with SAML-based federated identity providers to enable large teams to use NPK with minimal effort.

Configure how long data will stay in NPK with configurable lifecycle durations during installation. Hashfiles and results are automatically removed after this much time to keep things nicely cleaned up.

This fork adds the following security features to NPK:

• Dashboard Protection: Only whitelisted IPs can access the NPK web interface (CloudFront)
• API Security: Only whitelisted IPs can access the API endpoints (API Gateway)
• All other IPs will be blocked at the AWS infrastructure level
• Robust IP Handling: Enhanced IP processing ensures all specified IPs are properly applied to WAF configuration

• Automatic S3 Backup: IP restrictions and VPC tags are automatically backed up to S3
• Configuration Retrieval: When modifying an existing environment, previous configurations are automatically retrieved
• No Data Loss: Updates to an existing environment preserve all previous configuration choices
• Seamless Experience: Users don't need to reconfigure settings when updating their deployment

• Complete Public Access Block: All S3 buckets are protected from public access
• Four-Layer Protection: Blocks public ACLs, policies, and ignores any existing public access settings
• AWS services and Lambda functions still maintain proper access via IAM roles

• Automatically configures SSL certificates for custom domains
• Uses AWS ACM for certificate management

NPK allows you to add custom tags to AWS resources (including VPC endpoints) for better resource organization, cost allocation, and operational management. These tags are stored in aws_tags.json and can be modified on subsequent runs of the installation script.

To add or modify AWS resource tags during installation, follow these steps:

1. When prompted, choose to add AWS resource tags
2. Enter tag keys and values as prompted
3. Common tags include:
   • app_tagid - For financial tracking
   • Environment - e.g., production, staging, development
   • Owner - Team or individual responsible
   • Project - Project identifier
4. Tags will be applied to all supported AWS resources created by NPK

Example aws_tags.json:

{
  "tags": {
    "app_tagid": "your-app-id-here",
    "Environment": "production",
    "Owner": "security-team",
    "Project": "npk-deployment"
  }
}

ProTip: To keep things clean, it's recommended to deploy NPK in a fresh AWS account. You can create a new account from the 'Organizations' console in AWS.

If you said 'no' at the end of the installation wizard, you can run npm run deploy from the NPK prompt to finish the deployment.

See https://github.com/c6fc/npk/wiki/Detailed-NPK-Settings for more details about advanced configurations, or https://github.com/c6fc/npk/wiki/Configuring-SAML-SSO for help configuring SAML SSO.

Note: If you have an older version of NPK that you deployed without the one-liner, you'll need to destroy it before installing the new version

To connect to an existing NPK installation (which is needed to modify or uninstall NPK), log into the AWS account where NPK resides, click the CloudShell icon, and paste in the one-liner:

source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

CloudShell will now connect to NPK (which may take a minute or two), after which you'll drop to a new prompt that looks like this:

You're now connected to your NPK installation. This can be performed by any user in the AWS account with admin rights, and can be performed in any region.

You can change the settings of an install without losing your existing campaigns. Use the instructions above to connect to your NPK installation, then edit npk-settings.json as necessary and run npm run update. It's that easy!

cloudshell-user$ source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)
@bashguru/npk> vim npk-settings.json
< ... change your settings however you need >
@bashguru/npk> npm run update

Note: When modifying an existing installation, your previous IP restriction and VPC tag configurations will automatically be retrieved from S3. This ensures you don't have to start from scratch each time you run the installation script.

The NPK security-enhanced fork includes robust IP restriction management to ensure only authorized networks can access your deployment.

When you first deploy NPK, you'll be prompted to enter allowed IP addresses:

[*] Security Configuration - IP Restrictions
    Enter additional IP addresses to allow access (one per line)
    Press Enter on a blank line when finished.
    Format: 192.168.1.1 (for single IP) or 10.0.0.0/24 (with CIDR notation)

IP Address (or Enter to finish): 192.168.1.1
    Added 192.168.1.1/32 (single IP address)

If no IPs are specified, your current IP address will be used as default.

You can modify the IP addresses allowed to access your NPK deployment at any time:

1. Connect to your NPK installation using CloudShell:

cloudshell-user$ source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

2. When prompted, select "y" to modify IP restrictions:

Do you want to modify the IP restrictions? (y/n): y

3. If you have existing IP restrictions, you'll be prompted whether to keep them:

[*] Currently allowed IP addresses:
198.51.100.0/24
203.0.113.10/32

Would you like to keep existing IPs as a starting point? (y/n) [y]: y

[*] Starting with existing IP list. You can add or remove IPs.
  1) 198.51.100.0/24
  2) 203.0.113.10/32

4. You can selectively remove IPs from the existing list:

Would you like to remove any IPs from the list? (y/n) [n]: y
Enter number to remove (or Enter to finish): 2
    Removed IP: 203.0.113.10/32
    Updated IP list:
      1) 198.51.100.0/24
Enter number to remove (or Enter to finish): [ENTER to finish]

5. Enter additional IP addresses with proper validation (supports single IPs or CIDR notation):

IP Address (or Enter to finish): 192.168.1.1
    Added 192.168.1.1/32 (single IP address)
IP Address (or Enter to finish): 10.0.0.0/16
    Added 10.0.0.0/16
IP Address (or Enter to finish): invalid-ip
    Invalid IP format. Please use format like 192.168.1.1 or 10.0.0.0/24
IP Address (or Enter to finish): [ENTER to finish]

6. Continue with the installation process. Your new IP restrictions will be applied during deployment.

The script will automatically apply these IP restrictions to both the CloudFront distribution (web interface) and API Gateway endpoints. Single IPs without CIDR notation will automatically receive the /32 suffix for proper WAF configuration.

If you prefer a more direct approach, you can modify the IP configuration file manually using a text editor:

1. Connect to your NPK installation via CloudShell

2. Edit the IP configuration file directly:

   # Using nano
   nano /aws/mde/npk/ip_config.json
   
   # Or using vim
   vim /aws/mde/npk/ip_config.json

3. Modify the JSON structure to include your desired IPs:

   {
     "allowedIps": [
       "192.168.1.1/32",
       "10.0.0.0/24",
       "203.0.113.10/32"
     ]
   }

4. Save the file and then run the one-liner to apply your changes:

   source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

5. When prompted about modifying IP restrictions, choose "n" since you've already updated them manually.

Note: Your configuration will be automatically backed up to S3 after deployment, ensuring it persists for future modifications.

Similar to IP restrictions, you can also directly edit the VPC endpoint tags configuration file:

1. Connect to your NPK installation via CloudShell

2. Edit the AWS tags configuration file:

   # Using nano
   nano /aws/mde/npk/aws_tags.json
   
   # Or using vim
   vim /aws/mde/npk/aws_tags.json

3. Modify the JSON structure with your desired tag key-value pairs:

   {
     "tags": {
       "snowappid": "FIN0003447",
       "environment": "production",
       "purpose": "security-testing"
     }
   }

4. Save the file and then run the one-liner to apply your changes:

   source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

NPK implements a comprehensive tagging strategy that applies custom tags to all AWS resources for better organization, cost allocation, and resource management. Tags are stored in /aws/mde/npk/aws_tags.json and can be managed through the installation script.

1. Global Tagging: Tags are applied at the AWS provider level, ensuring they are automatically added to all supported AWS resources.
2. Resource-Specific Tags: Some resources may have additional tags specific to their function.
3. Tag Inheritance: All resources inherit tags from the provider configuration, with resource-specific tags taking precedence.

1. Run the installation script and choose to modify AWS resource tags when prompted:

   source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)

   [*] AWS Resource Tagging Configuration
   [*] Current AWS resource tags:
     Environment = production
     Owner = security-team
   Would you like to modify AWS resource tags? (y/n) [n]: y
   

2. You'll be guided through managing your tags. You can:

   • Add new tags
   • Modify existing tags
   • Remove existing tags

[*] Current AWS resource tags:
  1. Environment = production
  2. Owner = security-team

Choose an option:
  (a) Add new tag
  (m) Modify existing tag
  (r) Remove tag
  (d) Done
  
Your choice [d]: a

Enter tag name: Project
Enter value for 'Project': npk-deployment
[*] Added tag: Project = npk-deployment

3. When you're done, select 'd' to finish and confirm your changes.

For advanced users, you can manually edit the tags file:

# Using nano
nano /aws/mde/npk/aws_tags.json

# Or using vim
vim /aws/mde/npk/aws_tags.json

Edit the JSON structure with your desired tag key-value pairs:

{
  "tags": {
    "Environment": "production",
    "Owner": "security-team",
    "Project": "npk-deployment",
    "app_tagid": "FIN0003447"
  }
}

After saving the file, run the installation script again to apply your changes.

• Modifying Tags: Update tags at any time by running the installation script.
• Tag Propagation: Tags are applied to all supported AWS resources.
• Cost Allocation: Use tags like app_tagid for financial tracking.
• Resource Organization: Organize resources by environment, owner, or project.

1. Be Consistent: Use consistent naming conventions for tag keys and values.
2. Use Standard Tags: Standardize on common tags:
   • Environment (production, staging, development)
   • Owner (team or individual)
   • Project (project identifier)
   • CostCenter or app_tagid (for cost allocation)
3. Avoid Sensitive Data: Never store sensitive information in tags.
4. Tag Early: Configure tags during initial deployment.
5. Tag Limits: AWS allows up to 50 tags per resource.

• Tags are applied using Terraform's default_tags in the AWS provider configuration.
• Resource-specific tags take precedence over default tags.
• Tags are stored in S3 for persistence across deployments.
• The tagging system is backward compatible with the previous vpc_tags.json format.

Once NPK has been deployed, administrative users can use the NPK console to upload wordlists and rule files using the 'Dictionary Management' link in the sidebar. NPK supports plain-text and gzipped dictionaries.

You can completely turn down NPK and delete all of its data from AWS very easily. Just attach your CloudShell to NPK, then run npm run destroy:

cloudshell-user$ source <(curl -L https://raw.githubusercontent.com/bashguru/npk/main/bashguru_install.sh)
@bashguru/npk> npm run destroy

This section explains how to incorporate new changes from the original NPK repository without breaking the security enhancements in this fork.

1. Add the original repository as a remote (typically called "upstream"):

git remote add upstream https://github.com/c6fc/npk.git

2. Verify the remote was added successfully:

git remote -v
# You should see both origin (your fork) and upstream (original repo)

Follow these steps whenever you want to pull in changes from the original repository:

1. Fetch the latest changes from the upstream repository:

git fetch upstream

2. Ensure you're on your main branch:

git checkout main

3. Merge the changes from the upstream's main branch:

git merge upstream/main

4. Resolve any merge conflicts that occur:

# If there are conflicts, git will show you which files are affected
# Edit those files to resolve the conflicts (look for conflict markers)
# After resolving conflicts, mark them as resolved:
git add <filename>
# Complete the merge
git commit -m "Merge changes from upstream repository"

5. Push the merged changes to your GitHub repository:

git push origin main

When resolving conflicts, pay special attention to these files where your security enhancements exist:

• bashguru_install.sh: Contains IP validation and restriction management code
• ip_restrictions.libsonnet: IP whitelisting configuration
• aws/mde/npk/vpc_tags.json: VPC endpoint tagging configuration
• README.md: Documentation of security features

Always preserve your custom security code that handles:

• IP restriction validation and management
• VPC tagging functionality
• S3 bucket protection settings
• CloudFront security configurations

This project is a security-enhanced fork of NPK by c6fc.

For questions about the original NPK functionality, refer to the official project:

• Original NPK Repository

For community support on the original NPK project:

• Official NPK Discord