php-serialized-formatter 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '059244a56e51ddb0792c2c037873f656019ea069dd6c8b3617e85595b4fb6a53'
+  data.tar.gz: ad4c47309502acb762b9cf8dfb804d3ac5040914aa8fb4d5cb141648a0ea5f64
+SHA512:
+  metadata.gz: e5f968144bbf15c9cf8d0b3d3e546e86c4e76d4c51b9327f81e690d24aa5f683a06803de8a0dbef7437c98256c4561ada0ee62db6f204f6ad29c1902c45da2c6
+  data.tar.gz: be61df6b4acb9dbaf91a7aef59642aea213502f753e16b10a207d5a63392b03e290832175fcaa4910f42178e54ec5b0399e8def567a5a3ab17badd2bf720c3c1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandre ZANNI (noraj)
+
+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.

data/bin/psf

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'psf'
+require 'docopt'
+
+doc = <<~DOCOPT
+  php-serialized-formatter (psf) v#{Psf::VERSION}
+
+  Usage:
+    psf unserialize [--session] (--string <string> | --file <file> ) [--format <format>]
+    psf -h | --help
+    psf --version
+
+  Commands:
+    unserialize    Unserialize PHP serialized objects
+
+  Options:
+    --session                       Session mode [default: false]
+    -s <string>, --string <string>  Serialized content string, read from STDIN if equal to "-"
+    -f <file>, --file <file>        Serialized content file
+    --format <format>               Output format (hash, json, json_pretty, yaml) [default: hash]
+    --debug                         Display arguments
+    -h, --help                      Show this screen
+    --version                       Show version
+
+  Examples:
+    psf unserialize --session -f /var/lib/php/session/sess_3cebqoq314pcnc2jgqiu840h0k
+    psf unserialize -s 'O:6:"Person":2:{s:10:"first_name";s:4:"John";s:9:"last_name";s:3:"Doe";}' --format yaml
+
+  Project:
+    author (https://pwn.by/noraj / https://twitter.com/noraj_rawsec)
+    source (https://github.com/noraj/php-serialized-formatter)
+    documentation (https://noraj.github.io/php-serialized-formatter)
+DOCOPT
+
+begin
+  args = Docopt.docopt(doc, version: Psf::VERSION)
+  puts args if args['--debug']
+  # use case 1, using the tool
+  if args['unserialize']
+    # File or string ?
+    serialized_data = ''
+    if args['--string']
+      args['--string'] = $stdin.read.chomp if args['--string'] == '-'
+      serialized_data = args['--string']
+    elsif args['--file']
+      serialized_data = File.read(args['--file'])
+    end
+    # Session or regular object ?
+    unserialized_data = if args['--session']
+                          Psf.unserialize_session(serialized_data)
+                        else
+                          Psf.unserialize(serialized_data)
+                        end
+    # Format ?
+    case args['--format']
+    when 'hash'
+      require 'pp'
+      pp unserialized_data
+    when 'json'
+      require 'json'
+      puts unserialized_data.to_json
+    when 'json_pretty'
+      require 'json'
+      puts JSON.pretty_generate(unserialized_data)
+    when 'yaml'
+      require 'yaml'
+      puts unserialized_data.to_yaml
+    else
+      raise 'Unexisting format specified'
+    end
+  end
+  # use case 2, help: already handled by docopt
+  # use case 3, version: already handled by docopt
+rescue Docopt::Exit => e
+  puts e.message
+end

data/lib/psf/php_serial.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: false
+
+require 'psf/string_utils'
+
+# PHP serialization library that can parse and generate PHP's serialization
+# format including PHP sessions specific format.
+#
+# Thos module is a patched, modified and enhanced version of
+# [jurias/php-serial](https://github.com/jurias/php-serial/blob/master/lib/php-serial.rb)
+# (under [MIT license](https://github.com/jurias/php-serial/blob/master/LICENSE)).
+module Psf
+  # Serializes a ruby object into PHP serialized format.
+  # @param var [NilClass|Fixnum|Float|TrueClass|FalseClass|String|Array|Hash|Object]
+  # @return [String]
+  def self.serialize(var)
+    val = ''
+    case var.class.to_s
+    when 'NilClass'
+      val = 'N;'
+    when 'Integer', 'Fixnum', 'Bignum'
+      val = "i:#{var};"
+    when 'Float'
+      val = "d:#{var};"
+    when 'TrueClass'
+      val = 'b:1;'
+    when 'FalseClass'
+      val = 'b:0;'
+    when 'String', 'Symbol'
+      val = "s:#{var.to_s.bytesize}:\"#{var}\";"
+    when 'Array'
+      val = "a:#{var.length}:{"
+      var.length.times do |index|
+        val += serialize(index) + serialize(var[index])
+      end
+      val += '}'
+    when 'Hash'
+      val = "a:#{var.length}:{"
+      var.each do |item_key, item_value|
+        val += serialize(item_key) + serialize(item_value)
+      end
+      val += '}'
+    else
+      klass = var.class.to_s
+      val = "O:#{klass.length}:\"#{klass}\":#{var.instance_variables.length}:{"
+      var.instance_variables.each do |ivar|
+        ivar = ivar.to_s
+        ivar.slice!(0)
+        val += serialize(ivar) + serialize(var.send(ivar))
+      end
+      val += '}'
+    end
+    val
+  end
+
+  # Serializes a hash into PHP session.
+  # @param hash [Hash]
+  # @return [String]
+  def self.serialize_session(hash)
+    serialized_session = ''
+    hash.each do |key, value|
+      serialized_session += "#{key}|#{serialize(value)}"
+    end
+    serialized_session
+  end
+
+  # Unserializes a PHP session.
+  # @param data [String]
+  # @return [Hash]
+  def self.unserialize_session(data)
+    begin
+      data = data.strip
+    rescue Encoding::CompatibilityError
+      data = data.encode('UTF-8', invalid: :replace, undef: :replace).strip if data.encoding == Encoding::UTF_8
+    end
+    hash = {}
+
+    until data.empty?
+      key = extract_until!(data, '|')
+      hash[key] = unserialize!(data)
+    end
+    hash
+  end
+
+  # Unserializes a string up to the first valid serialized instance.
+  # @param data [String]
+  # @return [NilClass|Fixnum|Float|TrueClass|FalseClass|String|Array|Hash|Object]
+  def self.unserialize(data = '')
+    unserialize!(data.strip)
+  end
+
+  # Unserializes recursively. Consumes the input string.
+  # @param data [String]
+  # @return [NilClass|Fixnum|Float|TrueClass|FalseClass|String|Array|Hash|Object]
+  def self.unserialize!(data = '')
+    var_type = data.slice!(0)
+    data.slice!(0)
+    case var_type
+    when 'N'
+      value = nil
+    when 'b'
+      value = (extract_until!(data, ';') == '1')
+    when 's'
+      length = extract_until!(data, ':').to_i
+      extract_until!(data, '"')
+      value = data.byteslice!(0, length)
+      extract_until!(data, ';')
+    when 'i'
+      value = extract_until!(data, ';').to_i
+    when 'd'
+      value = extract_until!(data, ';').to_f
+    when 'a'
+      value = {}
+      length = extract_until!(data, ':').to_i
+      extract_until!(data, '{')
+      length.times do
+        key = unserialize!(data)
+        value[key] = unserialize!(data)
+      end
+      extract_until!(data, '}')
+      # if keys are sequential numbers, return array
+      value = value.values if (Array(0..value.length - 1) == value.keys) && !value.empty?
+    when 'O'
+      value = {}
+      length = extract_until!(data, ':').to_i
+      extract_until!(data, '"')
+      value['class'] = data.slice!(0, length)
+      extract_until!(data, ':')
+      length = extract_until!(data, ':').to_i
+      extract_until!(data, '{')
+      length.times do
+        key = unserialize!(data)
+        value[key] = unserialize!(data)
+      end
+    end
+    value
+  end
+
+  # Return all characters up to the first occurrence of char.
+  # Truncates those characters from input string.
+  # @param str [String]
+  # @param char [String]
+  # @return [String]
+  def self.extract_until!(str, char)
+    extracted = ''
+    while (c = str.slice!(0))
+      break if c == char
+
+      extracted << c
+    end
+    extracted
+  end
+end

data/lib/psf/string_utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Extending String class with new methods
+class String
+  # In place version of String#byteslice(index, length)
+  def byteslice!(start_index, length = nil)
+    byte_start_index = start_index
+    byte_length = length || (bytesize - byte_start_index)
+
+    byte_start_index = bytesize + byte_start_index if byte_start_index.negative?
+    return nil if byte_start_index.negative? || byte_start_index >= bytesize
+
+    byte_length = bytesize - byte_start_index if byte_start_index + byte_length > bytesize
+
+    out = byteslice(byte_start_index, byte_length)
+    replace(byteslice(0, byte_start_index) + byteslice(byte_start_index + byte_length..-1))
+    out
+  end
+end

data/lib/psf/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Psf
+  # Version of php-serialized-formatter library and app
+  VERSION = '0.0.1'
+end

data/lib/psf.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'psf/version'
+require 'psf/php_serial'

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: php-serialized-formatter
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexandre ZANNI
+bindir: bin
+cert_chain: []
+date: 2025-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: PHP serialization library that can parse and generate PHP'sserialization
+  format including PHP sessions specific format.
+email: alexandre.zanni@europe.com
+executables:
+- psf
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- bin/psf
+- lib/psf.rb
+- lib/psf/php_serial.rb
+- lib/psf/string_utils.rb
+- lib/psf/version.rb
+homepage: https://github.com/noraj/php-serialized-formatter
+licenses:
+- MIT
+metadata:
+  yard.run: yard
+  bug_tracker_uri: https://github.com/noraj/php-serialized-formatter/issues
+  changelog_uri: https://github.com/noraj/php-serialized-formatter/releases
+  documentation_uri: https://noraj.github.io/php-serialized-formatter/
+  homepage_uri: https://github.com/noraj/php-serialized-formatter
+  source_code_uri: https://github.com/noraj/php-serialized-formatter/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Serialize and unserialize to|from PHP session|objects.
+test_files: []