Merge pull request #54 from trustedsec/hashview

Hashview

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "hashcat-utils"]
+	path = hashcat-utils
+	url = https://github.com/hashcat/hashcat-utils.git

TESTING.md

@@ -0,0 +1,89 @@
+# Test Mocking Summary
+
+## Overview
+All Hashview API tests have been updated to use mocked responses instead of real API calls. This allows tests to run in CI/CD environments (like GitHub Actions) without requiring connectivity to a Hashview server or actual API credentials.
+
+## Changes Made
+
+### 1. Updated Test Files
+
+**test_hashview.py** (consolidated test suite)
+- Added `unittest.mock` imports (Mock, patch, MagicMock)
+- Removed dependency on config.json file
+- Replaced all real API calls with mocked responses
+- Mock responses match the actual API response format (e.g., 'users' field as JSON string)
+- Includes comprehensive tests for:
+  - Customer listing and validation
+  - Authentication and authorization
+  - Hashfile upload
+  - Complete job creation workflow
+
+### 2. Key Mock Patterns
+
+```python
+# Example: Mocking list_customers response
+mock_response = Mock()
+mock_response.json.return_value = {
+    'users': json.dumps([  # Note: 'users' is a JSON string in the real API
+        {'id': 1, 'name': 'Test Customer'}
+    ])
+}
+mock_response.raise_for_status = Mock()
+api.session.get.return_value = mock_response
+```
+
+### 3. GitHub Actions Workflow
+
+Created `.github/workflows/tests.yml` to automatically run tests on:
+- Push to main/master/develop branches
+- Pull requests to main/master/develop branches
+- Tests run against Python 3.9, 3.10, 3.11, and 3.12
+
+### 4. Documentation
+
+Updated readme.md with:
+- Testing section explaining how to run tests locally
+- Description of test structure
+- Information about CI/CD integration
+
+## Test Results
+
+✅ 6 tests passing  
+⚡ Tests run in ~0.1 seconds (vs ~20 seconds with real API calls)
+
+### Test Coverage
+
+1. **test_list_customers_success** - Validates customer listing with multiple customers
+2. **test_list_customers_returns_valid_data** - Validates customer data structure
+3. **test_connection_and_auth** - Tests successful authentication
+4. **test_invalid_api_key_fails** - Tests authentication failure handling
+5. **test_upload_hashfile** - Tests hashfile upload functionality
+6. **test_create_job_workflow** - Tests complete end-to-end job creation workflow
+
+## Benefits
+
+1. **No Dependencies**: Tests run without needing a Hashview server or API credentials
+2. **Fast Execution**: Mocked tests complete in milliseconds
+3. **Reliable**: Tests won't fail due to network issues or server downtime
+4. **CI/CD Ready**: Can run in GitHub Actions and other CI environments
+5. **Portable**: Tests work anywhere Python is installed
+
+## Running Tests
+
+```bash
+# Install dependencies
+pip install pytest pytest-mock requests
+
+# Run all tests
+pytest -v
+
+# Run specific test
+pytest test_hashview.py -v
+
+# Run a specific test method
+pytest test_hashview.py::TestHashviewAPI::test_create_job_workflow -v
+```
+
+## Note on Real API Testing
+
+While these mocked tests validate the code logic, you may still want to occasionally run integration tests against a real Hashview instance to ensure the API hasn't changed. The test files can be easily modified to toggle between mocked and real API calls if needed.

config.json.example

@@ -1,5 +1,5 @@
 {
-  "hcatPath": "/Passwords/hashcat",
+  "hcatPath": "",
   "hcatBin": "hashcat",
   "hcatTuning": "--force --remove",
   "hcatWordlists": "/Passwords/wordlists",
@@ -16,5 +16,7 @@
   "pipalPath": "/path/to/pipal",
   "pipal_count" : 10,
   "bandrelmaxruntime": 300,
-  "bandrel_common_basedwords": "welcome,password,p@ssword,p@$$word,changeme,letmein,summer,winter,spring,springtime,fall,autumn,monday,tuesday,wednesday,thursday,friday,saturday,sunday,january,february,march,april,may,june,july,august,september,october,november,december,christmas,easter,covid19"
+  "bandrel_common_basedwords": "welcome,password,p@ssword,p@$$word,changeme,letmein,summer,winter,spring,springtime,fall,autumn,monday,tuesday,wednesday,thursday,friday,saturday,sunday,january,february,march,april,may,june,july,august,september,october,november,december,christmas,easter,covid19",
+  "hashview_url": "http://localhost:8443",
+  "hashview_api_key": ""
 }

hashcat-utils/CHANGES

@@ -1,9 +0,0 @@
-* v1.1 -> v1.2
-
-- Open Source the project
-- License is MIT
-- Moved repository to github: https://github.com/hashcat/hashcat-utils
-- Added CHANGES
-- Added LICENSE
-- Added README.md
-

hashcat-utils/LICENSE

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

hashcat-utils/README.md

@@ -1,28 +0,0 @@
-hashcat-utils
-==============
-
-Hashcat-utils are a set of small utilities that are useful in advanced password cracking
-
-Brief description
---------------
-
-They all are packed into multiple stand-alone binaries.
-
-All of these utils are designed to execute only one specific function.
-
-Since they all work with STDIN and STDOUT you can group them into chains.
-
-Detailed description
---------------
-
-tbd
-
-Compile
---------------
-
-Simply run make
-
-Binary distribution
---------------
-
-Binaries for Linux, Windows and OSX: https://github.com/hashcat/hashcat-utils/releases

hashcat-utils/bin/seprule.pl

@@ -1,71 +0,0 @@
-#!/usr/bin/env perl
-
-## Name........: seprule
-## Autor.......: Jens Steube <jens.steube@gmail.com>
-## License.....: MIT
-
-use strict;
-use warnings;
-
-##
-## configuration
-##
-
-my @rp = ('0'..'9', 'A'..'Z');
-
-my $width = 3;
-my $rule  = "i";
-my $sep   = " ";
-
-##
-## code
-##
-
-my $rp_size = scalar @rp;
-
-my $total = $rp_size ** $width;
-
-my $db;
-
-for (my $i = 0; $i < $total; $i++)
-{
-  my $left = $i;
-
-  my @out;
-
-  for (my $c = 0; $c < $width; $c++)
-  {
-    my $m = $left % $rp_size;
-    my $d = $left / $rp_size;
-
-    push (@out, $m);
-
-    $left = $d;
-  }
-
-  @out = sort { $a <=> $b } @out;
-
-  my $val = join ("", @out);
-
-  next if (exists $db->{$val});
-
-  $db->{$val} = undef;
-
-  my @final;
-
-  for (my $c = 0; $c < $width; $c++)
-  {
-    my $s = sprintf ("T%s", $rp[$out[$c]]);
-
-    push (@final, $s);
-  }
-
-  for (my $c = 0; $c < $width; $c++)
-  {
-    my $s = sprintf ("%s%s%s", $rule, $rp[$out[$c]], $sep);
-
-    push (@final, $s);
-  }
-
-  print join (" ", "l", @final), "\n";
-}

hashcat-utils/bin/tmesis.pl

@@ -1,59 +0,0 @@
-#!/usr/bin/env perl
-
-## Name........: tmesis
-## Autor.......: Jens Steube <jens.steube@gmail.com>
-## License.....: MIT
-
-use strict;
-use warnings;
-
-#tmesis will take a wordlist and produce insertion rules that would insert each word of the wordlist to preset positions.
-#For example:
-#Word ‘password’ will create insertion rules that would insert ‘password’ from position 0 to position F (15)  and It will mutate the string ‘123456’ as follows.
-#password123456
-#1password23456
-#12password3456
-#123password456
-#1234password56
-#12345password6
-#123456password
-#
-#Hints:
-#*Use tmesis to create rules to attack hashlists the came from the source. Run initial analysis on the cracked passwords , collect the top 10 – 20 words appear on the passwords and use tmesis to generate rules.
-#*use tmesis generated rules in combination with best64.rules
-#
-# inspired by T0XlC
-
-my $min_rule_pos = 0;
-my $max_rule_pos = 15;
-
-my $db;
-
-my @intpos_to_rulepos = ('0'..'9', 'A'..'Z');
-
-my $function = "i";
-#my $function = "o";
-
-while (my $word = <>)
-{
-  chomp $word;
-
-  my $word_len = length $word;
-
-  my @word_buf = split "", $word;
-
-  for (my $rule_pos = $min_rule_pos; $rule_pos < $max_rule_pos - $word_len; $rule_pos++)
-  {
-    my @rule;
-
-    for (my $word_pos = 0; $word_pos < $word_len; $word_pos++)
-    {
-      my $function_full = $function . $intpos_to_rulepos[$rule_pos + $word_pos] . $word_buf[$word_pos];
-
-      push @rule, $function_full;
-    }
-
-    print join (" ", @rule), "\n";
-  }
-}
-

hashcat-utils/bin/topmorph.pl

@@ -1,71 +0,0 @@
-#!/usr/bin/env perl
-
-## Name........: topmorph
-## Autor.......: Jens Steube <jens.steube@gmail.com>
-## License.....: MIT
-
-use strict;
-use warnings;
-
-my @intpos_to_rulepos = ('0'..'9', 'A'..'Z');
-
-my $function = "i";
-#my $function = "o";
-
-if (scalar @ARGV != 5)
-{
-  print "usage: $0 dictionary depth width pos_min pos_max\n";
-
-  exit -1;
-}
-
-my ($dictionary, $depth, $width, $pos_min, $pos_max) = @ARGV;
-
-if ($width > 20)
-{
-  print "width > 20\n";
-
-  exit -1;
-}
-
-for (my $pos = $pos_min; $pos <= $pos_max; $pos++)
-{
-  my $db;
-
-  open (IN, $dictionary) or die "$dictionary: $!\n";
-
-  while (my $line = <IN>)
-  {
-    chomp $line;
-
-    my $len = length $line;
-
-    next if (($len - $pos) < $width);
-
-    my $word = substr ($line, $pos, $width);
-
-    next unless defined $word;
-
-    $db->{$word}++;
-  }
-
-  close (IN);
-
-  my @keys = sort { $db->{$b} <=> $db->{$a} } keys %{$db};
-
-  for (my $i = 0; $i < $depth; $i++)
-  {
-    my @chars = split "", $keys[$i];
-
-    my @rule;
-
-    for (my $j = 0; $j < $width; $j++)
-    {
-      my $function_full = join "", $function, $intpos_to_rulepos[$pos + $j], $chars[$j];
-
-      push @rule, $function_full;
-    }
-
-    print join (" ", @rule), "\n";
-  }
-}

readme.md

@@ -58,6 +58,39 @@ $ ./hate_crack.py <hash file> 1000
                           Version 1.09
   
 
+## Testing
+
+The project includes comprehensive test coverage for the Hashview integration.
+
+### Running Tests Locally
+
+```bash
+# Install test dependencies
+pip install pytest pytest-mock requests
+
+# Run all tests
+pytest -v
+
+# Run specific test
+pytest test_hashview.py -v
+```
+
+### Test Structure
+
+- **test_hashview.py**: Comprehensive test suite for HashviewAPI class with mocked API responses, including:
+  - Customer listing and data validation
+  - Authentication and authorization tests
+  - Hashfile upload functionality
+  - Complete job creation workflow
+
+All tests use mocked API calls, so they can run without connectivity to a Hashview server. This allows tests to run in CI/CD environments (like GitHub Actions) without requiring actual API credentials.
+
+### Continuous Integration
+
+Tests automatically run on GitHub Actions for every push and pull request. The workflow tests against multiple Python versions (3.9, 3.10, 3.11, 3.12) to ensure compatibility.
+
+-------------------------------------------------------------------
+
 	(1) Quick Crack
 	(2) Extensive Pure_Hate Methodology Crack
 	(3) Brute Force Attack

test_hashview.py

@@ -0,0 +1,284 @@
+"""
+Tests for Hashview integration - Mocked API calls for CI/CD
+"""
+import pytest
+import sys
+import os
+import json
+import tempfile
+from unittest.mock import Mock, patch, MagicMock
+
+# Add the parent directory to the path to import hate_crack
+sys.path.insert(0, os.path.dirname(__file__))
+
+from hate_crack import HashviewAPI
+
+# Test configuration - these are mock values, not real credentials
+HASHVIEW_URL = 'https://hashview.example.com'
+HASHVIEW_API_KEY = 'test-api-key-123'
+
+
+class TestHashviewAPI:
+    """Test suite for HashviewAPI class with mocked API calls"""
+    
+    @pytest.fixture
+    def api(self):
+        """Create a HashviewAPI instance with mocked session"""
+        with patch('hate_crack.requests.Session') as mock_session_class:
+            api = HashviewAPI(
+                base_url=HASHVIEW_URL,
+                api_key=HASHVIEW_API_KEY
+            )
+            # Replace the session with a mock
+            api.session = MagicMock()
+            yield api
+    
+    @pytest.fixture
+    def test_hashfile(self):
+        """Create a temporary test hashfile with NTLM hashes"""
+        test_hashes = [
+            "8846f7eaee8fb117ad06bdd830b7586c",  # password (NTLM)
+            "e19ccf75ee54e06b06a5907af13cef42",  # 123456 (NTLM)
+            "5835048ce94ad0564e29a924a03510ef",  # 12345678 (NTLM)
+        ]
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.txt', delete=False) as f:
+            hashfile_path = f.name
+            for hash_val in test_hashes:
+                f.write(hash_val + '\n')
+        
+        yield hashfile_path
+        
+        # Cleanup
+        if os.path.exists(hashfile_path):
+            os.unlink(hashfile_path)
+    
+    def test_list_customers_success(self, api):
+        """Test successful customer listing with mocked API call"""
+        # Mock the response - API returns 'users' as a JSON string
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            'users': json.dumps([
+                {'id': 1, 'name': 'Test Customer 1', 'description': 'Test description 1'},
+                {'id': 2, 'name': 'Test Customer 2', 'description': 'Test description 2'}
+            ])
+        }
+        mock_response.raise_for_status = Mock()
+        api.session.get.return_value = mock_response
+        
+        # Make API call
+        result = api.list_customers()
+        
+        # Assertions
+        assert result is not None
+        assert 'customers' in result
+        assert isinstance(result['customers'], list)
+        assert len(result['customers']) == 2
+        
+        # Print results for visibility
+        print(f"\nFound {len(result['customers'])} customers:")
+        for customer in result['customers']:
+            print(f"  ID: {customer.get('id')}, Name: {customer.get('name')}, Description: {customer.get('description', 'N/A')}")
+    
+    def test_list_customers_returns_valid_data(self, api):
+        """Test that customer data has expected structure"""
+        # Mock the response - API returns 'users' as a JSON string
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            'users': json.dumps([
+                {'id': 1, 'name': 'Test Customer', 'description': 'Test'}
+            ])
+        }
+        mock_response.raise_for_status = Mock()
+        api.session.get.return_value = mock_response
+        
+        result = api.list_customers()
+        
+        assert 'customers' in result
+        
+        # If there are customers, validate structure
+        if result['customers']:
+            for customer in result['customers']:
+                assert 'id' in customer
+                assert 'name' in customer
+                # Description is optional
+    
+    def test_connection_and_auth(self, api):
+        """Test that we can connect and authenticate"""
+        # Mock successful response - API returns 'users' as a JSON string
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            'users': json.dumps([
+                {'id': 1, 'name': 'Test Customer'}
+            ])
+        }
+        mock_response.raise_for_status = Mock()
+        api.session.get.return_value = mock_response
+        
+        result = api.list_customers()
+        assert result is not None
+        
+        # Valid response should have 'customers' key
+        assert 'customers' in result, "Valid authentication should return customers data"
+        
+        print(f"\n✓ Successfully connected to {HASHVIEW_URL}")
+        print(f"✓ Authentication successful")
+    
+    def test_invalid_api_key_fails(self):
+        """Test that an invalid API key results in authentication failure"""
+        with patch('hate_crack.requests.Session') as mock_session_class:
+            # Create API instance with invalid API key
+            invalid_api = HashviewAPI(
+                base_url=HASHVIEW_URL,
+                api_key="invalid-api-key-123-this-should-fail"
+            )
+            
+            # Mock error response
+            mock_session = MagicMock()
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                'type': 'Error',
+                'msg': 'You are not authorized to perform this action',
+                'status': 401
+            }
+            mock_response.raise_for_status = Mock()
+            mock_session.get.return_value = mock_response
+            invalid_api.session = mock_session
+            
+            # Attempt to list customers with invalid key
+            result = invalid_api.list_customers()
+            
+            # API returns 200 but with error message in response body
+            assert result is not None
+            assert 'type' in result
+            assert result['type'] == 'Error'
+            assert 'msg' in result
+            assert 'not authorized' in result['msg'].lower()
+            
+            print(f"\n✓ Invalid API key correctly rejected")
+            print(f"  Error message: {result['msg']}")
+    
+    def test_upload_hashfile(self, api, test_hashfile):
+        """Test uploading a hashfile to Hashview"""
+        print("\n[Test] Uploading hashfile...")
+        
+        # Mock list_customers response - API returns 'users' as a JSON string
+        mock_customers_response = Mock()
+        mock_customers_response.json.return_value = {
+            'users': json.dumps([{'id': 1, 'name': 'Test Customer'}])
+        }
+        mock_customers_response.raise_for_status = Mock()
+        
+        # Mock upload_hashfile response
+        mock_upload_response = Mock()
+        mock_upload_response.json.return_value = {
+            'hashfile_id': 4567,
+            'msg': 'Hashfile added'
+        }
+        mock_upload_response.raise_for_status = Mock()
+        
+        # Set up session mock to return different responses
+        api.session.get.return_value = mock_customers_response
+        api.session.post.return_value = mock_upload_response
+        
+        # Get first customer
+        customers_result = api.list_customers()
+        customer_id = customers_result['customers'][0]['id']
+        
+        # Upload hashfile
+        hash_type = 1000  # NTLM
+        file_format = 5  # hash_only
+        hashfile_name = "test_hashfile_automated"
+        
+        upload_result = api.upload_hashfile(
+            test_hashfile,
+            customer_id,
+            hash_type,
+            file_format,
+            hashfile_name
+        )
+        
+        assert upload_result is not None, "No upload result returned"
+        assert 'hashfile_id' in upload_result, "No hashfile_id returned"
+        
+        print(f"  ✓ Hashfile uploaded successfully")
+        print(f"  ✓ Hashfile ID: {upload_result['hashfile_id']}")
+    
+    def test_create_job_workflow(self, api, test_hashfile):
+        """Test creating a job in Hashview (option 2 complete workflow)"""
+        print("\n" + "="*60)
+        print("Testing Option 2: Create Job Workflow")
+        print("="*60)
+        
+        # Mock responses for different endpoints - API returns 'users' as a JSON string
+        mock_customers_response = Mock()
+        mock_customers_response.json.return_value = {
+            'users': json.dumps([{'id': 1, 'name': 'Test Customer'}])
+        }
+        mock_customers_response.raise_for_status = Mock()
+        
+        mock_upload_response = Mock()
+        mock_upload_response.json.return_value = {
+            'hashfile_id': 4567,
+            'msg': 'Hashfile added'
+        }
+        mock_upload_response.raise_for_status = Mock()
+        
+        mock_job_response = Mock()
+        mock_job_response.json.return_value = {
+            'job_id': 789,
+            'msg': 'Job added'
+        }
+        mock_job_response.raise_for_status = Mock()
+        
+        # Configure session mock
+        api.session.get.return_value = mock_customers_response
+        api.session.post.side_effect = [mock_upload_response, mock_job_response]
+        
+        # Step 1: Get test customer
+        print("\n[Step 1] Getting test customer...")
+        customers_result = api.list_customers()
+        test_customer = customers_result['customers'][0]
+        customer_id = test_customer['id']
+        print(f"  ✓ Using customer ID: {customer_id} ({test_customer['name']})")
+        
+        # Step 2: Upload hashfile
+        print("\n[Step 2] Uploading hashfile...")
+        hash_type = 1000  # NTLM
+        file_format = 5  # hash_only
+        hashfile_name = "test_hashfile_automated"
+        
+        upload_result = api.upload_hashfile(
+            test_hashfile,
+            customer_id,
+            hash_type,
+            file_format,
+            hashfile_name
+        )
+        
+        hashfile_id = upload_result['hashfile_id']
+        print(f"  ✓ Hashfile ID: {hashfile_id}")
+        
+        # Step 3: Create job
+        print("\n[Step 3] Creating job...")
+        job_name = "test_job_automated"
+        
+        job_result = api.create_job(
+            name=job_name,
+            hashfile_id=hashfile_id,
+            customer_id=customer_id
+        )
+        
+        assert job_result is not None, "No job result returned"
+        print(f"  ✓ Job created successfully")
+        
+        if 'job_id' in job_result:
+            print(f"  ✓ Job ID: {job_result['job_id']}")
+        
+        print("\n" + "="*60)
+        print("✓ Option 2 (Create Job) is READY and WORKING!")
+        print("="*60)
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])