concuss 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ead6fff82661378bb379172fb4e62a3d22c5a312d363cc9c49a8ebce268e40
-  data.tar.gz: 9bce360c65581ef6ec55ecd6084609680fff69a4480f7ef75041a8cb1c8df756
+  metadata.gz: ebbc8f1ad06752a93ba6b66ef4fa666a693532a792b71d14ff830ae1a7537494
+  data.tar.gz: 8a1b02193ffb5bac321fbad3a4905c7b00f9ddfec1df543ab755aba9c564b4e2
 SHA512:
-  metadata.gz: 5f83174439a0930992841f179026927addfd43b3aab14ce08738959f28a04a23eff6b40d83ca610586b5d23aa22c9073d59c0fa04843e0fe15bcf8f865a51302
-  data.tar.gz: 517db0408b735b4f4741f720f23222e5c9ab2f4cdc5b09f3a943df65e54b33dfc68256bcd3b9fda1d350c597003b6ce7cbb6bcc08e39a6b15f8d1233872f2ad3
+  metadata.gz: f9407c5f49b7dc5b2f03ad0b69e00e21b6f1940ea6167c630ffe59fd4366bd1e099c68e061fe2943c9c3c41ff4103ce781b50e9ed85a268627ab7e2fe41b0050
+  data.tar.gz: e891c23429f6931b81bf9b00a9b38bb4ecb361ebc3c40d35dead0b7f5510e8a7ed33cd88c27dbb532d438baed12126cabf588cf04dc82448e64b45584402a0a3

data/CHANGELOG.md

@@ -1,5 +1,7 @@
-## [Unreleased]
+## [0.2.0] - 2023-01-29
+
+* Add support for custom user agents. If none provided, used a default user agent that identifies itself as Concuss/VERSION
 
 ## [0.1.0] - 2023-01-18
 
-- Initial release
+* Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    concuss (0.1.0)
+    concuss (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,11 +1,16 @@
 # Concuss
 
+[![Gem Version](https://badge.fury.io/rb/concuss.svg)](https://badge.fury.io/rb/concuss)
+[![Build Status](https://github.com/patricktulskie/concuss/actions/workflows/main.yml/badge.svg)](https://github.com/patricktulskie/concuss/actions/workflows/main.yml)
+
 ## What is it?
 
 Concuss is a tool for banging against a url with a bunch of different headers to look for potential vulnerabilities.
 
 It works by sending a custom or a random string to a webserver for a specific url in a variety of headers to see if it's able to get that string to appear on the page. If so, you'll get a HIT and you can evaluate that header to see if it's useful for some kind of XSS, cache poisoning, or some other form of injection from malformed headers.
 
+Often times web app and framework developers assume that headers from the client are not malicious or manipulated and will just write them out to the page in one form or another. This project is a specialized tool to find instances of this so that they can be fixed before they are abused.
+
 ## What it is NOT.
 
 Concuss is not a tool for automating vulnerabilities, nor should it be used to certify that a page is safe from vulnerabilities. It should not be used on applications or website that you do not personally have permission to scan.
@@ -39,17 +44,39 @@ While concuss is designed to be used as a command line tool, you can also includ
 require 'concuss'
 
 concuss = Concuss.new(url: 'http://localhost:4567', file: 'header_file.txt', header_set: :standard, test_string: "OOGABOOGA")
-concuss.attack!
+report = concuss.attack!
 ```
 
-This will spit out the results, which isn't super useful if you need to post process them... I'll work on that though.
+From there, you'll get a `Concuss::Report` object that contains the raw data as well as filters for `hits`, `misses`, `headers`, and the `url` in the event you've done a bunch of these.
+
+## Demo
+
+There is a sample app with a vulnerability to test with in the `vuln_app` directory. It takes the contents of `X-CSRF-Token` and spits them out blindly.
+
+Here's some steps to get going with that:
+
+```
+docker-compose build
+docker-compose run console bash
+
+# You should see the vuln_app container boot up and
+# then you'll land in bash on the console container
+
+bin/concuss http://vuln_app:4567 -h non_standard
+```
 
 ## Development
 
-After checking out the repo, run `script/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `script/console` for an interactive prompt that will allow you to experiment.
+Primarily, you'll want to use Docker to do debugging and development. To get into the console, just run `docker-compose run console bash` and from there you can run `bin/concuss` against the sample vulnerable app, or you can run `rspec` to run the specs.
+
+If you prefer to develop without docker, after checking out the repo, run `bundle install` to install dependencies. Then, run `rspec` to run the tests.
+
+When developing using docker or on your bare machine you can also run `script/console` for an interactive prompt that will allow you to experiment. This will give you access to the underlying classes and let you experiment outside the confines of the CLI.
 
 If you add features or fix bugs, please write specs and open up a PR.
 
+Note: Concuss was designed to easily install on most systems with ruby 3+. As such, its only dependencies are in the ruby standard library.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/patricktulskie/concuss

data/bin/concuss

@@ -19,6 +19,10 @@ OptionParser.new do |opts|
   opts.on("-t", "--test-string STRING", "Set a custom test string. If none specified, it sets a random string to match on.") do |v|
     options[:test_string] = v
   end
+
+  opts.on("-a", "--user-agent STRING", "Set a custom user agent. If none specified, it defaults to Concuss/#{Concuss::VERSION}") do |v|
+    options[:user_agent] = v
+  end
 end.parse!
 
 if ARGV[0].nil?
@@ -27,5 +31,9 @@ if ARGV[0].nil?
 end
 
 options[:url] = ARGV[0]
+options[:formatter] = Concuss::Formatters::Table
+options[:progress_type] = :dots
+
+puts "Scanning #{options[:url]}"
 
 Concuss.new(**options).attack!

data/lib/concuss/formatters/table.rb

@@ -0,0 +1,31 @@
+class Concuss::Formatters::Table
+
+  HEADINGS = ['HEADER', 'RESPONSE_CODE', 'HIT/MISS'].freeze
+
+  def initialize(report)
+    @report = report
+  end
+
+  def print
+    header_max_length = @report.headers.map(&:length).max
+    response_code_length = HEADINGS[1].length
+    hit_header_length = HEADINGS[2].length
+
+    header_format = "%-#{header_max_length}s | %-#{response_code_length}s | %-0s\n"
+    separator = '-' * (header_max_length + response_code_length + hit_header_length + 6)
+
+    puts header_format % HEADINGS
+    puts separator
+    print_data(@report.hits, header_format)
+    print_data(@report.misses, header_format)
+  end
+
+  private
+
+  def print_data(data, header_format)
+    data.sort.each do |header, values|
+      puts header_format % [header, values[:response_code], values[:hit] ? 'HIT' : 'MISS']
+    end
+  end
+end
+

data/lib/concuss/formatters.rb

@@ -0,0 +1,6 @@
+class Concuss
+  module Formatters
+  end
+end
+
+require_relative 'formatters/table'

data/lib/concuss/headers.rb

@@ -30,7 +30,6 @@ class Concuss::Headers
     'Range',
     'Referer',
     'TE',
-    'User-Agent',
     'Upgrade',
     'Via',
     'Warning'

data/lib/concuss/report.rb

@@ -0,0 +1,20 @@
+class Concuss::Report
+  attr_reader :data, :url
+
+  def initialize(data:, url:)
+    @url = url
+    @data = data
+  end
+
+  def hits
+    data.select { |_, value| value[:hit] }
+  end
+
+  def misses
+    data.reject { |_, value| value[:hit] }
+  end
+
+  def headers
+    data.keys
+  end
+end

data/lib/concuss/runner.rb

@@ -2,30 +2,44 @@ require 'securerandom'
 require 'net/http'
 
 class Concuss::Runner
-  attr_reader :headers, :url, :test_string
+  DEFAULT_USER_AGENT = "Concuss/#{Concuss::VERSION}"
 
-  def initialize(headers:, url:, test_string: nil)
+  attr_reader :headers, :url, :test_string, :user_agent, :progress_type
+
+  def initialize(headers:, url:, test_string: nil, user_agent: nil, progress_type: nil)
     @headers = headers
     @url = url
     @test_string = test_string || SecureRandom.hex(25)
+    @user_agent = user_agent || DEFAULT_USER_AGENT
+    @progress_type = progress_type
   end
 
   def run
     uri = URI(@url)
+    report_data = { }
 
     @headers.each do |header|
       response = Net::HTTP.get_response(uri,
-        { header => test_string }
+        {
+          header => test_string,
+          'User-Agent' => user_agent
+        }
       )
 
-      if response.code == "200" && response.body.include?(@test_string)
-        result = "HIT"
-      else
-        result = "MISS"
-      end
+      hit = response.code == "200" && response.body.include?(@test_string)
+      report_data[header] = { response_code: response.code, hit: hit }
 
-      puts "#{header} - #{response.code} - #{result}"
+      case progress_type
+      when :full
+        puts "#{header} - #{response.code} - #{hit ? "HIT" : "MISS"}"
+      when :dots
+        print "."
+      end
     end
+
+    puts "" if progress_type == :dots
+
+    return Concuss::Report.new(data: report_data, url: @url)
   end
 end
 

data/lib/concuss/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Concuss
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/concuss.rb

@@ -3,24 +3,32 @@
 class Concuss
   class Error < StandardError; end
 
-  attr_reader :url, :file, :header_set, :headers, :test_string
+  attr_reader :url, :file, :header_set, :headers, :test_string, :user_agent, :formatter, :progress_type
 
-  def initialize(url:, file: nil, header_set: :all, test_string: nil)
+  def initialize(url:, file: nil, header_set: :all, test_string: nil, user_agent: nil, formatter: nil, progress_type: nil)
     @url = url
     @file = file
     @header_set = file.nil? ? header_set : :file
     @test_string = test_string
+    @user_agent = user_agent
+    @formatter = formatter
+    @progress_type = progress_type
 
     @headers = Concuss::Headers.new(header_set: @header_set, file: @file).group
   end
 
   def attack!
-    runner = Concuss::Runner.new(headers: headers, url: url, test_string: test_string)
+    runner = Concuss::Runner.new(headers: headers, url: url, test_string: test_string, user_agent: user_agent, progress_type: progress_type)
+    results = runner.run
 
-    runner.run
+    formatter.new(results).print if formatter
+
+    return results
   end
 end
 
 require_relative "concuss/version"
+require_relative "concuss/report"
 require_relative "concuss/headers"
 require_relative "concuss/runner"
+require_relative "concuss/formatters"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concuss
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick Tulskie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-21 00:00:00.000000000 Z
+date: 2023-02-04 00:00:00.000000000 Z
 dependencies: []
 description: Test websites for header injection issues
 email:
@@ -27,7 +27,10 @@ files:
 - Rakefile
 - bin/concuss
 - lib/concuss.rb
+- lib/concuss/formatters.rb
+- lib/concuss/formatters/table.rb
 - lib/concuss/headers.rb
+- lib/concuss/report.rb
 - lib/concuss/runner.rb
 - lib/concuss/version.rb
 homepage: https://github.com/patricktulskie/concuss
@@ -45,7 +48,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="